Index.h revision 198893
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> 20198893Srdivacky 21198092Srdivacky#ifdef __cplusplus 22198092Srdivackyextern "C" { 23198092Srdivacky#endif 24198092Srdivacky 25198893Srdivacky/* MSVC DLL import/export. */ 26198893Srdivacky#ifdef _MSC_VER 27198893Srdivacky #ifdef _CINDEX_LIB_ 28198893Srdivacky #define CINDEX_LINKAGE __declspec(dllexport) 29198893Srdivacky #else 30198893Srdivacky #define CINDEX_LINKAGE __declspec(dllimport) 31198893Srdivacky #endif 32198893Srdivacky#else 33198893Srdivacky #define CINDEX_LINKAGE 34198893Srdivacky#endif 35198893Srdivacky 36198092Srdivacky/* 37198092Srdivacky Clang indeX abstractions. The backing store for the following API's will be 38198092Srdivacky clangs AST file (currently based on PCH). AST files are created as follows: 39198092Srdivacky 40198092Srdivacky "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>". 41198092Srdivacky 42198092Srdivacky Naming Conventions: To avoid namespace pollution, data types are prefixed 43198092Srdivacky with "CX" and functions are prefixed with "clang_". 44198092Srdivacky*/ 45198092Srdivackytypedef void *CXIndex; /* An indexing instance. */ 46198092Srdivacky 47198092Srdivackytypedef void *CXTranslationUnit; /* A translation unit instance. */ 48198092Srdivacky 49198893Srdivackytypedef void *CXFile; /* A source file */ 50198092Srdivackytypedef void *CXDecl; /* A specific declaration within a translation unit. */ 51198092Srdivackytypedef void *CXStmt; /* A specific statement within a function/method */ 52198092Srdivacky 53198092Srdivacky/* Cursors represent declarations, definitions, and references. */ 54198092Srdivackyenum CXCursorKind { 55198092Srdivacky /* Declarations */ 56198092Srdivacky CXCursor_FirstDecl = 1, 57198092Srdivacky CXCursor_TypedefDecl = 2, 58198092Srdivacky CXCursor_StructDecl = 3, 59198092Srdivacky CXCursor_UnionDecl = 4, 60198092Srdivacky CXCursor_ClassDecl = 5, 61198092Srdivacky CXCursor_EnumDecl = 6, 62198092Srdivacky CXCursor_FieldDecl = 7, 63198092Srdivacky CXCursor_EnumConstantDecl = 8, 64198092Srdivacky CXCursor_FunctionDecl = 9, 65198092Srdivacky CXCursor_VarDecl = 10, 66198092Srdivacky CXCursor_ParmDecl = 11, 67198092Srdivacky CXCursor_ObjCInterfaceDecl = 12, 68198092Srdivacky CXCursor_ObjCCategoryDecl = 13, 69198092Srdivacky CXCursor_ObjCProtocolDecl = 14, 70198092Srdivacky CXCursor_ObjCPropertyDecl = 15, 71198092Srdivacky CXCursor_ObjCIvarDecl = 16, 72198092Srdivacky CXCursor_ObjCInstanceMethodDecl = 17, 73198092Srdivacky CXCursor_ObjCClassMethodDecl = 18, 74198092Srdivacky CXCursor_LastDecl = 18, 75198092Srdivacky 76198092Srdivacky /* Definitions */ 77198092Srdivacky CXCursor_FirstDefn = 32, 78198092Srdivacky CXCursor_FunctionDefn = 32, 79198092Srdivacky CXCursor_ObjCClassDefn = 33, 80198092Srdivacky CXCursor_ObjCCategoryDefn = 34, 81198092Srdivacky CXCursor_ObjCInstanceMethodDefn = 35, 82198092Srdivacky CXCursor_ObjCClassMethodDefn = 36, 83198092Srdivacky CXCursor_LastDefn = 36, 84198092Srdivacky 85198092Srdivacky /* References */ 86198092Srdivacky CXCursor_FirstRef = 40, /* Decl references */ 87198092Srdivacky CXCursor_ObjCSuperClassRef = 40, 88198092Srdivacky CXCursor_ObjCProtocolRef = 41, 89198092Srdivacky CXCursor_ObjCClassRef = 42, 90198092Srdivacky 91198092Srdivacky CXCursor_ObjCSelectorRef = 43, /* Expression references */ 92198092Srdivacky CXCursor_ObjCIvarRef = 44, 93198092Srdivacky CXCursor_VarRef = 45, 94198092Srdivacky CXCursor_FunctionRef = 46, 95198092Srdivacky CXCursor_EnumConstantRef = 47, 96198092Srdivacky CXCursor_MemberRef = 48, 97198092Srdivacky CXCursor_LastRef = 48, 98198092Srdivacky 99198092Srdivacky /* Error conditions */ 100198092Srdivacky CXCursor_FirstInvalid = 70, 101198092Srdivacky CXCursor_InvalidFile = 70, 102198092Srdivacky CXCursor_NoDeclFound = 71, 103198092Srdivacky CXCursor_NotImplemented = 72, 104198092Srdivacky CXCursor_LastInvalid = 72 105198092Srdivacky}; 106198092Srdivacky 107198092Srdivacky/* A cursor into the CXTranslationUnit. */ 108198092Srdivacky 109198092Srdivackytypedef struct { 110198092Srdivacky enum CXCursorKind kind; 111198092Srdivacky CXDecl decl; 112198092Srdivacky CXStmt stmt; /* expression reference */ 113198092Srdivacky} CXCursor; 114198092Srdivacky 115198092Srdivacky/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */ 116198398Srdivackytypedef void *CXEntity; 117198092Srdivacky 118198398Srdivacky/** 119198398Srdivacky * \brief clang_createIndex() provides a shared context for creating 120198398Srdivacky * translation units. It provides two options: 121198398Srdivacky * 122198398Srdivacky * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 123198398Srdivacky * declarations (when loading any new translation units). A "local" declaration 124198398Srdivacky * is one that belongs in the translation unit itself and not in a precompiled 125198398Srdivacky * header that was used by the translation unit. If zero, all declarations 126198398Srdivacky * will be enumerated. 127198398Srdivacky * 128198398Srdivacky * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, 129198398Srdivacky * diagnostics will be ignored. 130198398Srdivacky * 131198398Srdivacky * Here is an example: 132198398Srdivacky * 133198398Srdivacky * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 134198398Srdivacky * Idx = clang_createIndex(1, 1); 135198398Srdivacky * 136198398Srdivacky * // IndexTest.pch was produced with the following command: 137198398Srdivacky * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 138198398Srdivacky * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 139198398Srdivacky * 140198398Srdivacky * // This will load all the symbols from 'IndexTest.pch' 141198398Srdivacky * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); 142198398Srdivacky * clang_disposeTranslationUnit(TU); 143198398Srdivacky * 144198398Srdivacky * // This will load all the symbols from 'IndexTest.c', excluding symbols 145198398Srdivacky * // from 'IndexTest.pch'. 146198398Srdivacky * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; 147198398Srdivacky * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); 148198398Srdivacky * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); 149198398Srdivacky * clang_disposeTranslationUnit(TU); 150198398Srdivacky * 151198398Srdivacky * This process of creating the 'pch', loading it separately, and using it (via 152198398Srdivacky * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 153198398Srdivacky * (which gives the indexer the same performance benefit as the compiler). 154198398Srdivacky */ 155198893SrdivackyCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 156198398Srdivacky int displayDiagnostics); 157198893SrdivackyCINDEX_LINKAGE void clang_disposeIndex(CXIndex); 158198092Srdivacky 159198893SrdivackyCINDEX_LINKAGE const char *clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 160198092Srdivacky 161198398Srdivacky/* 162198398Srdivacky * \brief Create a translation unit from an AST file (-emit-ast). 163198398Srdivacky */ 164198893SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( 165198092Srdivacky CXIndex, const char *ast_filename 166198092Srdivacky); 167198398Srdivacky/** 168198398Srdivacky * \brief Destroy the specified CXTranslationUnit object. 169198398Srdivacky */ 170198893SrdivackyCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 171198092Srdivacky 172198398Srdivacky/** 173198398Srdivacky * \brief Return the CXTranslationUnit for a given source file and the provided 174198398Srdivacky * command line arguments one would pass to the compiler. 175198398Srdivacky * 176198398Srdivacky * Note: The 'source_filename' argument is optional. If the caller provides a NULL pointer, 177198398Srdivacky * the name of the source file is expected to reside in the specified command line arguments. 178198398Srdivacky * 179198398Srdivacky * Note: When encountered in 'clang_command_line_args', the following options are ignored: 180198398Srdivacky * 181198398Srdivacky * '-c' 182198398Srdivacky * '-emit-ast' 183198398Srdivacky * '-fsyntax-only' 184198398Srdivacky * '-o <output file>' (both '-o' and '<output file>' are ignored) 185198398Srdivacky * 186198398Srdivacky */ 187198893SrdivackyCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 188198398Srdivacky CXIndex CIdx, 189198398Srdivacky const char *source_filename /* specify NULL if the source file is in clang_command_line_args */, 190198398Srdivacky int num_clang_command_line_args, 191198398Srdivacky const char **clang_command_line_args 192198398Srdivacky); 193198398Srdivacky 194198092Srdivacky/* 195198092Srdivacky Usage: clang_loadTranslationUnit(). Will load the toplevel declarations 196198092Srdivacky within a translation unit, issuing a 'callback' for each one. 197198092Srdivacky 198198092Srdivacky void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) { 199198092Srdivacky if (clang_getCursorKind(C) == Cursor_Declaration) { 200198092Srdivacky CXDecl D = clang_getCursorDecl(C); 201198092Srdivacky if (clang_getDeclKind(D) == CXDecl_ObjC_interface) 202198092Srdivacky printf("@interface %s in file %s on line %d column %d\n", 203198092Srdivacky clang_getDeclSpelling(D), clang_getCursorSource(C), 204198092Srdivacky clang_getCursorLine(C), clang_getCursorColumn(C)); 205198092Srdivacky } 206198092Srdivacky } 207198092Srdivacky static void usage { 208198092Srdivacky clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames); 209198092Srdivacky } 210198092Srdivacky*/ 211198092Srdivackytypedef void *CXClientData; 212198092Srdivackytypedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor, 213198092Srdivacky CXClientData); 214198893SrdivackyCINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit, CXTranslationUnitIterator, 215198092Srdivacky CXClientData); 216198092Srdivacky 217198092Srdivacky/* 218198092Srdivacky Usage: clang_loadDeclaration(). Will load the declaration, issuing a 219198092Srdivacky 'callback' for each declaration/reference within the respective declaration. 220198092Srdivacky 221198092Srdivacky For interface declarations, this will index the super class, protocols, 222198092Srdivacky ivars, methods, etc. For structure declarations, this will index the fields. 223198092Srdivacky For functions, this will index the parameters (and body, for function 224198092Srdivacky definitions), local declarations/references. 225198092Srdivacky 226198092Srdivacky void getInterfaceDetails(CXDecl X, CXCursor C) { 227198092Srdivacky switch (clang_getCursorKind(C)) { 228198092Srdivacky case Cursor_ObjC_ClassRef: 229198092Srdivacky CXDecl SuperClass = clang_getCursorDecl(C); 230198092Srdivacky case Cursor_ObjC_ProtocolRef: 231198092Srdivacky CXDecl AdoptsProtocol = clang_getCursorDecl(C); 232198092Srdivacky case Cursor_Declaration: 233198092Srdivacky CXDecl AnIvarOrMethod = clang_getCursorDecl(C); 234198092Srdivacky } 235198092Srdivacky } 236198092Srdivacky static void usage() { 237198092Srdivacky if (clang_getDeclKind(D) == CXDecl_ObjC_interface) { 238198092Srdivacky clang_loadDeclaration(D, getInterfaceDetails); 239198092Srdivacky } 240198092Srdivacky } 241198092Srdivacky*/ 242198092Srdivackytypedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData); 243198092Srdivacky 244198893SrdivackyCINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData); 245198092Srdivacky 246198092Srdivacky/* 247198893Srdivacky * CXFile Operations. 248198893Srdivacky */ 249198893SrdivackyCINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); 250198893SrdivackyCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 251198893Srdivacky 252198893Srdivacky/* 253198092Srdivacky * CXEntity Operations. 254198092Srdivacky */ 255198893SrdivackyCINDEX_LINKAGE const char *clang_getDeclarationName(CXEntity); 256198893SrdivackyCINDEX_LINKAGE const char *clang_getURI(CXEntity); 257198893SrdivackyCINDEX_LINKAGE CXEntity clang_getEntity(const char *URI); 258198092Srdivacky/* 259198092Srdivacky * CXDecl Operations. 260198092Srdivacky */ 261198893SrdivackyCINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl); 262198893SrdivackyCINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXDecl); 263198893SrdivackyCINDEX_LINKAGE const char *clang_getDeclSpelling(CXDecl); 264198893SrdivackyCINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl); 265198893SrdivackyCINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl); 266198893SrdivackyCINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */ 267198893SrdivackyCINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl); 268198092Srdivacky 269198092Srdivacky/* 270198092Srdivacky * CXCursor Operations. 271198092Srdivacky */ 272198398Srdivacky/** 273198398Srdivacky Usage: clang_getCursor() will translate a source/line/column position 274198398Srdivacky into an AST cursor (to derive semantic information from the source code). 275198398Srdivacky */ 276198893SrdivackyCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, const char *source_name, 277198092Srdivacky unsigned line, unsigned column); 278198092Srdivacky 279198893SrdivackyCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 280198893SrdivackyCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 281198893SrdivackyCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 282198893SrdivackyCINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind); 283198893SrdivackyCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 284198398Srdivacky 285198893SrdivackyCINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor); 286198893SrdivackyCINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor); 287198893SrdivackyCINDEX_LINKAGE const char *clang_getCursorSpelling(CXCursor); 288198893SrdivackyCINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */ 289198893SrdivackyCINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor); 290198398Srdivacky 291198092Srdivacky/* for debug/testing */ 292198893SrdivackyCINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); 293198893SrdivackyCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 294198092Srdivacky const char **startBuf, 295198092Srdivacky const char **endBuf, 296198092Srdivacky unsigned *startLine, 297198092Srdivacky unsigned *startColumn, 298198092Srdivacky unsigned *endLine, 299198092Srdivacky unsigned *endColumn); 300198092Srdivacky 301198092Srdivacky/* 302198092Srdivacky * If CXCursorKind == Cursor_Reference, then this will return the referenced 303198092Srdivacky * declaration. 304198092Srdivacky * If CXCursorKind == Cursor_Declaration, then this will return the declaration. 305198092Srdivacky */ 306198893SrdivackyCINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor); 307198092Srdivacky 308198092Srdivacky#ifdef __cplusplus 309198092Srdivacky} 310198092Srdivacky#endif 311198092Srdivacky#endif 312198092Srdivacky 313