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