Index.h revision 50398199fb10e196a8d92fbf7a062dbe42ed88fd 
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 PCH file (which contains AST's, or Abstract Syntax Trees). PCH files
26   are created by the following command:
27
28   "clang -emit-pch <sourcefile.langsuffix> -o <sourcefile.ast>".
29
30   If the ast file format ends up diverging from the pch file format, we will
31   need to add a new switch (-emit-ast). For now, the contents are identical.
32
33   Naming Conventions: To avoid namespace pollution, data types are prefixed
34   with "CX" and functions are prefixed with "clang_".
35*/
36typedef void *CXIndex;            /* An indexing instance. */
37
38typedef void *CXTranslationUnit;  /* A translation unit instance. */
39
40typedef void *CXCursor;  /* An opaque cursor into the CXTranslationUnit. */
41
42/* Cursors represent declarations and references (provides line/column info). */
43enum CXCursorKind {
44 CXCursor_Declaration,
45 CXCursor_Reference,
46 CXCursor_ObjC_ClassRef,
47 CXCursor_ObjC_ProtocolRef,
48 CXCursor_ObjC_MessageRef,
49 CXCursor_ObjC_SelectorRef
50};
51
52typedef void *CXDecl;    /* A specific declaration within a translation unit. */
53
54enum CXDeclKind {  /* The various kinds of declarations. */
55 CXDecl_any,
56 CXDecl_typedef,
57 CXDecl_enum,
58 CXDecl_enum_constant,
59 CXDecl_record,
60 CXDecl_field,
61 CXDecl_function,
62 CXDecl_variable,
63 CXDecl_parameter,
64 CXDecl_ObjC_interface,
65 CXDecl_ObjC_category,
66 CXDecl_ObjC_protocol,
67 CXDecl_ObjC_property,
68 CXDecl_ObjC_instance_variable,
69 CXDecl_ObjC_instance_method,
70 CXDecl_ObjC_class_method,
71 CXDecl_ObjC_category_implementation,
72 CXDecl_ObjC_class_implementation,
73 CXDecl_ObjC_property_implementation
74};
75
76/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */
77typedef void *CXEntity;
78
79CXIndex clang_createIndex();
80
81CXTranslationUnit clang_createTranslationUnit(
82  CXIndex, const char *ast_filename
83);
84
85/*
86   Usage: clang_loadTranslationUnit(). Will load the toplevel declarations
87   within a translation unit, issuing a 'callback' for each one.
88
89   void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) {
90     if (clang_getCursorKind(C) == Cursor_Declaration) {
91       CXDecl D = clang_getCursorDecl(C);
92       if (clang_getDeclKind(D) == CXDecl_ObjC_interface)
93         printf("@interface %s in file %s on line %d column %d\n",
94                clang_getDeclSpelling(D), clang_getCursorSource(C),
95                clang_getCursorLine(C), clang_getCursorColumn(C));
96     }
97   }
98   static void usage {
99     clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames);
100   }
101*/
102void clang_loadTranslationUnit(
103  CXTranslationUnit, void (*callback)(CXTranslationUnit, CXCursor)
104);
105
106/*
107   Usage: clang_loadDeclaration(). Will load the declaration, issuing a
108   'callback' for each declaration/reference within the respective declaration.
109
110   For interface declarations, this will index the super class, protocols,
111   ivars, methods, etc. For structure declarations, this will index the fields.
112   For functions, this will index the parameters (and body, for function
113   definitions), local declarations/references.
114
115   void getInterfaceDetails(CXDecl X, CXCursor C) {
116     switch (clang_getCursorKind(C)) {
117       case Cursor_ObjC_ClassRef:
118         CXDecl SuperClass = clang_getCursorDecl(C);
119       case Cursor_ObjC_ProtocolRef:
120         CXDecl AdoptsProtocol = clang_getCursorDecl(C);
121       case Cursor_Declaration:
122         CXDecl AnIvarOrMethod = clang_getCursorDecl(C);
123     }
124   }
125   static void usage() {
126     if (clang_getDeclKind(D) == CXDecl_ObjC_interface) {
127       clang_loadDeclaration(D, getInterfaceDetails);
128     }
129   }
130*/
131void clang_loadDeclaration(CXDecl, void (*callback)(CXDecl, CXCursor));
132
133/*
134 * CXEntity Operations.
135 */
136const char *clang_getDeclarationName(CXEntity);
137const char *clang_getURI(CXEntity);
138CXEntity clang_getEntity(const char *URI);
139/*
140 * CXDecl Operations.
141 */
142CXCursor clang_getCursorFromDecl(CXDecl);
143CXEntity clang_getEntityFromDecl(CXDecl);
144enum CXDeclKind clang_getDeclKind(CXDecl);
145const char *clang_getDeclSpelling(CXDecl);
146/*
147 * CXCursor Operations.
148 */
149CXCursor clang_getCursor(CXTranslationUnit, const char *source_name,
150                         unsigned line, unsigned column);
151
152enum CXCursorKind clang_getCursorKind(CXCursor);
153
154unsigned clang_getCursorLine(CXCursor);
155unsigned clang_getCursorColumn(CXCursor);
156const char *clang_getCursorSource(CXCursor);
157
158/*
159 * If CXCursorKind == Cursor_Reference, then this will return the referenced declaration.
160 * If CXCursorKind == Cursor_Declaration, then this will return the declaration.
161 */
162CXDecl clang_getCursorDecl(CXCursor);
163
164#ifdef __cplusplus
165}
166#endif
167#endif
168
169