Index.h revision 08b0e8daeb683686b876d72674962ad96df21d45 
1/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
2|*                                                                            *|
3|*                     The LLVM Compiler Infrastructure                       *|
4|*                                                                            *|
5|* This file is distributed under the University of Illinois Open Source      *|
6|* License. See LICENSE.TXT for details.                                      *|
7|*                                                                            *|
8|*===----------------------------------------------------------------------===*|
9|*                                                                            *|
10|* This header provides a public inferface to a Clang library for extracting  *|
11|* high-level symbol information from source files without exposing the full  *|
12|* Clang C++ API.                                                             *|
13|*                                                                            *|
14\*===----------------------------------------------------------------------===*/
15
16#ifndef CLANG_C_INDEX_H
17#define CLANG_C_INDEX_H
18
19#include <sys/stat.h>
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25/* MSVC DLL import/export. */
26#ifdef _MSC_VER
27  #ifdef _CINDEX_LIB_
28    #define CINDEX_LINKAGE __declspec(dllexport)
29  #else
30    #define CINDEX_LINKAGE __declspec(dllimport)
31  #endif
32#else
33  #define CINDEX_LINKAGE
34#endif
35
36/*
37   Clang indeX abstractions. The backing store for the following API's will be
38   clangs AST file (currently based on PCH). AST files are created as follows:
39
40   "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>".
41
42   Naming Conventions: To avoid namespace pollution, data types are prefixed
43   with "CX" and functions are prefixed with "clang_".
44*/
45typedef void *CXIndex;            /* An indexing instance. */
46
47typedef void *CXTranslationUnit;  /* A translation unit instance. */
48
49typedef void *CXFile;    /* A source file */
50typedef void *CXDecl;    /* A specific declaration within a translation unit. */
51typedef void *CXStmt;    /* A specific statement within a function/method */
52
53/* Cursors represent declarations, definitions, and references. */
54enum CXCursorKind {
55 /* Declarations */
56 CXCursor_FirstDecl                     = 1,
57 CXCursor_TypedefDecl                   = 2,
58 CXCursor_StructDecl                    = 3,
59 CXCursor_UnionDecl                     = 4,
60 CXCursor_ClassDecl                     = 5,
61 CXCursor_EnumDecl                      = 6,
62 CXCursor_FieldDecl                     = 7,
63 CXCursor_EnumConstantDecl              = 8,
64 CXCursor_FunctionDecl                  = 9,
65 CXCursor_VarDecl                       = 10,
66 CXCursor_ParmDecl                      = 11,
67 CXCursor_ObjCInterfaceDecl             = 12,
68 CXCursor_ObjCCategoryDecl              = 13,
69 CXCursor_ObjCProtocolDecl              = 14,
70 CXCursor_ObjCPropertyDecl              = 15,
71 CXCursor_ObjCIvarDecl                  = 16,
72 CXCursor_ObjCInstanceMethodDecl        = 17,
73 CXCursor_ObjCClassMethodDecl           = 18,
74 CXCursor_LastDecl                      = 18,
75
76 /* Definitions */
77 CXCursor_FirstDefn                     = 32,
78 CXCursor_FunctionDefn                  = 32,
79 CXCursor_ObjCClassDefn                 = 33,
80 CXCursor_ObjCCategoryDefn              = 34,
81 CXCursor_ObjCInstanceMethodDefn        = 35,
82 CXCursor_ObjCClassMethodDefn           = 36,
83 CXCursor_LastDefn                      = 36,
84
85 /* References */
86 CXCursor_FirstRef                      = 40, /* Decl references */
87 CXCursor_ObjCSuperClassRef             = 40,
88 CXCursor_ObjCProtocolRef               = 41,
89 CXCursor_ObjCClassRef                  = 42,
90
91 CXCursor_ObjCSelectorRef               = 43, /* Expression references */
92 CXCursor_ObjCIvarRef                   = 44,
93 CXCursor_VarRef                        = 45,
94 CXCursor_FunctionRef                   = 46,
95 CXCursor_EnumConstantRef               = 47,
96 CXCursor_MemberRef                     = 48,
97 CXCursor_LastRef                       = 48,
98
99 /* Error conditions */
100 CXCursor_FirstInvalid                  = 70,
101 CXCursor_InvalidFile                   = 70,
102 CXCursor_NoDeclFound                   = 71,
103 CXCursor_NotImplemented                = 72,
104 CXCursor_LastInvalid                   = 72
105};
106
107/* A cursor into the CXTranslationUnit. */
108
109typedef struct {
110  enum CXCursorKind kind;
111  CXDecl decl;
112  CXStmt stmt; /* expression reference */
113} CXCursor;
114
115/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */
116typedef void *CXEntity;
117
118/**
119 * \brief clang_createIndex() provides a shared context for creating
120 * translation units. It provides two options:
121 *
122 * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
123 * declarations (when loading any new translation units). A "local" declaration
124 * is one that belongs in the translation unit itself and not in a precompiled
125 * header that was used by the translation unit. If zero, all declarations
126 * will be enumerated.
127 *
128 * - displayDiagnostics: when non-zero, diagnostics will be output. If zero,
129 * diagnostics will be ignored.
130 *
131 * Here is an example:
132 *
133 *   // excludeDeclsFromPCH = 1, displayDiagnostics = 1
134 *   Idx = clang_createIndex(1, 1);
135 *
136 *   // IndexTest.pch was produced with the following command:
137 *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
138 *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
139 *
140 *   // This will load all the symbols from 'IndexTest.pch'
141 *   clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
142 *   clang_disposeTranslationUnit(TU);
143 *
144 *   // This will load all the symbols from 'IndexTest.c', excluding symbols
145 *   // from 'IndexTest.pch'.
146 *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 };
147 *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args);
148 *   clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0);
149 *   clang_disposeTranslationUnit(TU);
150 *
151 * This process of creating the 'pch', loading it separately, and using it (via
152 * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
153 * (which gives the indexer the same performance benefit as the compiler).
154 */
155CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
156                          int displayDiagnostics);
157CINDEX_LINKAGE void clang_disposeIndex(CXIndex);
158
159CINDEX_LINKAGE const char *clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
160
161/*
162 * \brief Create a translation unit from an AST file (-emit-ast).
163 */
164CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(
165  CXIndex, const char *ast_filename
166);
167/**
168 * \brief Destroy the specified CXTranslationUnit object.
169 */
170CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
171
172/**
173 * \brief Return the CXTranslationUnit for a given source file and the provided
174 * command line arguments one would pass to the compiler.
175 *
176 * Note: The 'source_filename' argument is optional.  If the caller provides a NULL pointer,
177 *  the name of the source file is expected to reside in the specified command line arguments.
178 *
179 * Note: When encountered in 'clang_command_line_args', the following options are ignored:
180 *
181 *   '-c'
182 *   '-emit-ast'
183 *   '-fsyntax-only'
184 *   '-o <output file>'  (both '-o' and '<output file>' are ignored)
185 *
186 */
187CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
188  CXIndex CIdx,
189  const char *source_filename /* specify NULL if the source file is in clang_command_line_args */,
190  int num_clang_command_line_args,
191  const char **clang_command_line_args
192);
193
194/*
195   Usage: clang_loadTranslationUnit(). Will load the toplevel declarations
196   within a translation unit, issuing a 'callback' for each one.
197
198   void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) {
199     if (clang_getCursorKind(C) == Cursor_Declaration) {
200       CXDecl D = clang_getCursorDecl(C);
201       if (clang_getDeclKind(D) == CXDecl_ObjC_interface)
202         printf("@interface %s in file %s on line %d column %d\n",
203                clang_getDeclSpelling(D), clang_getCursorSource(C),
204                clang_getCursorLine(C), clang_getCursorColumn(C));
205     }
206   }
207   static void usage {
208     clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames);
209   }
210*/
211typedef void *CXClientData;
212typedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor,
213                                          CXClientData);
214CINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit, CXTranslationUnitIterator,
215                               CXClientData);
216
217/*
218   Usage: clang_loadDeclaration(). Will load the declaration, issuing a
219   'callback' for each declaration/reference within the respective declaration.
220
221   For interface declarations, this will index the super class, protocols,
222   ivars, methods, etc. For structure declarations, this will index the fields.
223   For functions, this will index the parameters (and body, for function
224   definitions), local declarations/references.
225
226   void getInterfaceDetails(CXDecl X, CXCursor C) {
227     switch (clang_getCursorKind(C)) {
228       case Cursor_ObjC_ClassRef:
229         CXDecl SuperClass = clang_getCursorDecl(C);
230       case Cursor_ObjC_ProtocolRef:
231         CXDecl AdoptsProtocol = clang_getCursorDecl(C);
232       case Cursor_Declaration:
233         CXDecl AnIvarOrMethod = clang_getCursorDecl(C);
234     }
235   }
236   static void usage() {
237     if (clang_getDeclKind(D) == CXDecl_ObjC_interface) {
238       clang_loadDeclaration(D, getInterfaceDetails);
239     }
240   }
241*/
242typedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData);
243
244CINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData);
245
246/*
247 * CXFile Operations.
248 */
249CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile);
250CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
251
252/*
253 * CXEntity Operations.
254 */
255CINDEX_LINKAGE const char *clang_getDeclarationName(CXEntity);
256CINDEX_LINKAGE const char *clang_getURI(CXEntity);
257CINDEX_LINKAGE CXEntity clang_getEntity(const char *URI);
258/*
259 * CXDecl Operations.
260 */
261CINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl);
262CINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXDecl);
263CINDEX_LINKAGE const char *clang_getDeclSpelling(CXDecl);
264CINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl);
265CINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl);
266CINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */
267CINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl);
268
269/*
270 * CXCursor Operations.
271 */
272/**
273   Usage: clang_getCursor() will translate a source/line/column position
274   into an AST cursor (to derive semantic information from the source code).
275 */
276CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, const char *source_name,
277                         unsigned line, unsigned column);
278
279CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
280CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
281CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
282CINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind);
283CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
284
285CINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor);
286CINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor);
287CINDEX_LINKAGE const char *clang_getCursorSpelling(CXCursor);
288CINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */
289CINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor);
290
291/* for debug/testing */
292CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind);
293CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor,
294                                          const char **startBuf,
295                                          const char **endBuf,
296                                          unsigned *startLine,
297                                          unsigned *startColumn,
298                                          unsigned *endLine,
299                                          unsigned *endColumn);
300
301/*
302 * If CXCursorKind == Cursor_Reference, then this will return the referenced
303 * declaration.
304 * If CXCursorKind == Cursor_Declaration, then this will return the declaration.
305 */
306CINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor);
307
308#ifdef __cplusplus
309}
310#endif
311#endif
312
313