]>
Commit | Line | Data |
---|---|---|
223e47cc LB |
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 | #include <time.h> | |
21 | #include <stdio.h> | |
22 | ||
23 | #include "clang-c/Platform.h" | |
24 | #include "clang-c/CXString.h" | |
25 | ||
26 | #ifdef __cplusplus | |
27 | extern "C" { | |
28 | #endif | |
29 | ||
30 | /** \defgroup CINDEX libclang: C Interface to Clang | |
31 | * | |
32 | * The C Interface to Clang provides a relatively small API that exposes | |
33 | * facilities for parsing source code into an abstract syntax tree (AST), | |
34 | * loading already-parsed ASTs, traversing the AST, associating | |
35 | * physical source locations with elements within the AST, and other | |
36 | * facilities that support Clang-based development tools. | |
37 | * | |
38 | * This C interface to Clang will never provide all of the information | |
39 | * representation stored in Clang's C++ AST, nor should it: the intent is to | |
40 | * maintain an API that is relatively stable from one release to the next, | |
41 | * providing only the basic functionality needed to support development tools. | |
42 | * | |
43 | * To avoid namespace pollution, data types are prefixed with "CX" and | |
44 | * functions are prefixed with "clang_". | |
45 | * | |
46 | * @{ | |
47 | */ | |
48 | ||
49 | /** | |
50 | * \brief An "index" that consists of a set of translation units that would | |
51 | * typically be linked together into an executable or library. | |
52 | */ | |
53 | typedef void *CXIndex; | |
54 | ||
55 | /** | |
56 | * \brief A single translation unit, which resides in an index. | |
57 | */ | |
58 | typedef struct CXTranslationUnitImpl *CXTranslationUnit; | |
59 | ||
60 | /** | |
61 | * \brief Opaque pointer representing client data that will be passed through | |
62 | * to various callbacks and visitors. | |
63 | */ | |
64 | typedef void *CXClientData; | |
65 | ||
66 | /** | |
67 | * \brief Provides the contents of a file that has not yet been saved to disk. | |
68 | * | |
69 | * Each CXUnsavedFile instance provides the name of a file on the | |
70 | * system along with the current contents of that file that have not | |
71 | * yet been saved to disk. | |
72 | */ | |
73 | struct CXUnsavedFile { | |
74 | /** | |
75 | * \brief The file whose contents have not yet been saved. | |
76 | * | |
77 | * This file must already exist in the file system. | |
78 | */ | |
79 | const char *Filename; | |
80 | ||
81 | /** | |
82 | * \brief A buffer containing the unsaved contents of this file. | |
83 | */ | |
84 | const char *Contents; | |
85 | ||
86 | /** | |
87 | * \brief The length of the unsaved contents of this buffer. | |
88 | */ | |
89 | unsigned long Length; | |
90 | }; | |
91 | ||
92 | /** | |
93 | * \brief Describes the availability of a particular entity, which indicates | |
94 | * whether the use of this entity will result in a warning or error due to | |
95 | * it being deprecated or unavailable. | |
96 | */ | |
97 | enum CXAvailabilityKind { | |
98 | /** | |
99 | * \brief The entity is available. | |
100 | */ | |
101 | CXAvailability_Available, | |
102 | /** | |
103 | * \brief The entity is available, but has been deprecated (and its use is | |
104 | * not recommended). | |
105 | */ | |
106 | CXAvailability_Deprecated, | |
107 | /** | |
108 | * \brief The entity is not available; any use of it will be an error. | |
109 | */ | |
110 | CXAvailability_NotAvailable, | |
111 | /** | |
112 | * \brief The entity is available, but not accessible; any use of it will be | |
113 | * an error. | |
114 | */ | |
115 | CXAvailability_NotAccessible | |
116 | }; | |
117 | ||
118 | /** | |
119 | * \brief Describes a version number of the form major.minor.subminor. | |
120 | */ | |
121 | typedef struct CXVersion { | |
122 | /** | |
123 | * \brief The major version number, e.g., the '10' in '10.7.3'. A negative | |
124 | * value indicates that there is no version number at all. | |
125 | */ | |
126 | int Major; | |
127 | /** | |
128 | * \brief The minor version number, e.g., the '7' in '10.7.3'. This value | |
129 | * will be negative if no minor version number was provided, e.g., for | |
130 | * version '10'. | |
131 | */ | |
132 | int Minor; | |
133 | /** | |
134 | * \brief The subminor version number, e.g., the '3' in '10.7.3'. This value | |
135 | * will be negative if no minor or subminor version number was provided, | |
136 | * e.g., in version '10' or '10.7'. | |
137 | */ | |
138 | int Subminor; | |
139 | } CXVersion; | |
140 | ||
141 | /** | |
142 | * \brief Provides a shared context for creating translation units. | |
143 | * | |
144 | * It provides two options: | |
145 | * | |
146 | * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" | |
147 | * declarations (when loading any new translation units). A "local" declaration | |
148 | * is one that belongs in the translation unit itself and not in a precompiled | |
149 | * header that was used by the translation unit. If zero, all declarations | |
150 | * will be enumerated. | |
151 | * | |
152 | * Here is an example: | |
153 | * | |
154 | * \code | |
155 | * // excludeDeclsFromPCH = 1, displayDiagnostics=1 | |
156 | * Idx = clang_createIndex(1, 1); | |
157 | * | |
158 | * // IndexTest.pch was produced with the following command: | |
159 | * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" | |
160 | * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); | |
161 | * | |
162 | * // This will load all the symbols from 'IndexTest.pch' | |
163 | * clang_visitChildren(clang_getTranslationUnitCursor(TU), | |
164 | * TranslationUnitVisitor, 0); | |
165 | * clang_disposeTranslationUnit(TU); | |
166 | * | |
167 | * // This will load all the symbols from 'IndexTest.c', excluding symbols | |
168 | * // from 'IndexTest.pch'. | |
169 | * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; | |
170 | * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, | |
171 | * 0, 0); | |
172 | * clang_visitChildren(clang_getTranslationUnitCursor(TU), | |
173 | * TranslationUnitVisitor, 0); | |
174 | * clang_disposeTranslationUnit(TU); | |
175 | * \endcode | |
176 | * | |
177 | * This process of creating the 'pch', loading it separately, and using it (via | |
178 | * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks | |
179 | * (which gives the indexer the same performance benefit as the compiler). | |
180 | */ | |
181 | CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, | |
182 | int displayDiagnostics); | |
183 | ||
184 | /** | |
185 | * \brief Destroy the given index. | |
186 | * | |
187 | * The index must not be destroyed until all of the translation units created | |
188 | * within that index have been destroyed. | |
189 | */ | |
190 | CINDEX_LINKAGE void clang_disposeIndex(CXIndex index); | |
191 | ||
192 | typedef enum { | |
193 | /** | |
194 | * \brief Used to indicate that no special CXIndex options are needed. | |
195 | */ | |
196 | CXGlobalOpt_None = 0x0, | |
197 | ||
198 | /** | |
199 | * \brief Used to indicate that threads that libclang creates for indexing | |
200 | * purposes should use background priority. | |
201 | * | |
202 | * Affects #clang_indexSourceFile, #clang_indexTranslationUnit, | |
203 | * #clang_parseTranslationUnit, #clang_saveTranslationUnit. | |
204 | */ | |
205 | CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1, | |
206 | ||
207 | /** | |
208 | * \brief Used to indicate that threads that libclang creates for editing | |
209 | * purposes should use background priority. | |
210 | * | |
211 | * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt, | |
212 | * #clang_annotateTokens | |
213 | */ | |
214 | CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2, | |
215 | ||
216 | /** | |
217 | * \brief Used to indicate that all threads that libclang creates should use | |
218 | * background priority. | |
219 | */ | |
220 | CXGlobalOpt_ThreadBackgroundPriorityForAll = | |
221 | CXGlobalOpt_ThreadBackgroundPriorityForIndexing | | |
222 | CXGlobalOpt_ThreadBackgroundPriorityForEditing | |
223 | ||
224 | } CXGlobalOptFlags; | |
225 | ||
226 | /** | |
227 | * \brief Sets general options associated with a CXIndex. | |
228 | * | |
229 | * For example: | |
230 | * \code | |
231 | * CXIndex idx = ...; | |
232 | * clang_CXIndex_setGlobalOptions(idx, | |
233 | * clang_CXIndex_getGlobalOptions(idx) | | |
234 | * CXGlobalOpt_ThreadBackgroundPriorityForIndexing); | |
235 | * \endcode | |
236 | * | |
237 | * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags. | |
238 | */ | |
239 | CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); | |
240 | ||
241 | /** | |
242 | * \brief Gets the general options associated with a CXIndex. | |
243 | * | |
244 | * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that | |
245 | * are associated with the given CXIndex object. | |
246 | */ | |
247 | CINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex); | |
248 | ||
249 | /** | |
250 | * \defgroup CINDEX_FILES File manipulation routines | |
251 | * | |
252 | * @{ | |
253 | */ | |
254 | ||
255 | /** | |
256 | * \brief A particular source file that is part of a translation unit. | |
257 | */ | |
258 | typedef void *CXFile; | |
259 | ||
260 | ||
261 | /** | |
262 | * \brief Retrieve the complete file and path name of the given file. | |
263 | */ | |
264 | CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); | |
265 | ||
266 | /** | |
267 | * \brief Retrieve the last modification time of the given file. | |
268 | */ | |
269 | CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); | |
270 | ||
271 | /** | |
272 | * \brief Determine whether the given header is guarded against | |
273 | * multiple inclusions, either with the conventional | |
274 | * \#ifndef/\#define/\#endif macro guards or with \#pragma once. | |
275 | */ | |
276 | CINDEX_LINKAGE unsigned | |
277 | clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file); | |
278 | ||
279 | /** | |
280 | * \brief Retrieve a file handle within the given translation unit. | |
281 | * | |
282 | * \param tu the translation unit | |
283 | * | |
284 | * \param file_name the name of the file. | |
285 | * | |
286 | * \returns the file handle for the named file in the translation unit \p tu, | |
287 | * or a NULL file handle if the file was not a part of this translation unit. | |
288 | */ | |
289 | CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, | |
290 | const char *file_name); | |
291 | ||
292 | /** | |
293 | * @} | |
294 | */ | |
295 | ||
296 | /** | |
297 | * \defgroup CINDEX_LOCATIONS Physical source locations | |
298 | * | |
299 | * Clang represents physical source locations in its abstract syntax tree in | |
300 | * great detail, with file, line, and column information for the majority of | |
301 | * the tokens parsed in the source code. These data types and functions are | |
302 | * used to represent source location information, either for a particular | |
303 | * point in the program or for a range of points in the program, and extract | |
304 | * specific location information from those data types. | |
305 | * | |
306 | * @{ | |
307 | */ | |
308 | ||
309 | /** | |
310 | * \brief Identifies a specific source location within a translation | |
311 | * unit. | |
312 | * | |
313 | * Use clang_getExpansionLocation() or clang_getSpellingLocation() | |
314 | * to map a source location to a particular file, line, and column. | |
315 | */ | |
316 | typedef struct { | |
317 | void *ptr_data[2]; | |
318 | unsigned int_data; | |
319 | } CXSourceLocation; | |
320 | ||
321 | /** | |
322 | * \brief Identifies a half-open character range in the source code. | |
323 | * | |
324 | * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the | |
325 | * starting and end locations from a source range, respectively. | |
326 | */ | |
327 | typedef struct { | |
328 | void *ptr_data[2]; | |
329 | unsigned begin_int_data; | |
330 | unsigned end_int_data; | |
331 | } CXSourceRange; | |
332 | ||
333 | /** | |
334 | * \brief Retrieve a NULL (invalid) source location. | |
335 | */ | |
336 | CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); | |
337 | ||
338 | /** | |
339 | * \brief Determine whether two source locations, which must refer into | |
340 | * the same translation unit, refer to exactly the same point in the source | |
341 | * code. | |
342 | * | |
343 | * \returns non-zero if the source locations refer to the same location, zero | |
344 | * if they refer to different locations. | |
345 | */ | |
346 | CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, | |
347 | CXSourceLocation loc2); | |
348 | ||
349 | /** | |
350 | * \brief Retrieves the source location associated with a given file/line/column | |
351 | * in a particular translation unit. | |
352 | */ | |
353 | CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, | |
354 | CXFile file, | |
355 | unsigned line, | |
356 | unsigned column); | |
357 | /** | |
358 | * \brief Retrieves the source location associated with a given character offset | |
359 | * in a particular translation unit. | |
360 | */ | |
361 | CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, | |
362 | CXFile file, | |
363 | unsigned offset); | |
364 | ||
365 | /** | |
366 | * \brief Retrieve a NULL (invalid) source range. | |
367 | */ | |
368 | CINDEX_LINKAGE CXSourceRange clang_getNullRange(); | |
369 | ||
370 | /** | |
371 | * \brief Retrieve a source range given the beginning and ending source | |
372 | * locations. | |
373 | */ | |
374 | CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, | |
375 | CXSourceLocation end); | |
376 | ||
377 | /** | |
378 | * \brief Determine whether two ranges are equivalent. | |
379 | * | |
380 | * \returns non-zero if the ranges are the same, zero if they differ. | |
381 | */ | |
382 | CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, | |
383 | CXSourceRange range2); | |
384 | ||
385 | /** | |
386 | * \brief Returns non-zero if \p range is null. | |
387 | */ | |
388 | CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); | |
389 | ||
390 | /** | |
391 | * \brief Retrieve the file, line, column, and offset represented by | |
392 | * the given source location. | |
393 | * | |
394 | * If the location refers into a macro expansion, retrieves the | |
395 | * location of the macro expansion. | |
396 | * | |
397 | * \param location the location within a source file that will be decomposed | |
398 | * into its parts. | |
399 | * | |
400 | * \param file [out] if non-NULL, will be set to the file to which the given | |
401 | * source location points. | |
402 | * | |
403 | * \param line [out] if non-NULL, will be set to the line to which the given | |
404 | * source location points. | |
405 | * | |
406 | * \param column [out] if non-NULL, will be set to the column to which the given | |
407 | * source location points. | |
408 | * | |
409 | * \param offset [out] if non-NULL, will be set to the offset into the | |
410 | * buffer to which the given source location points. | |
411 | */ | |
412 | CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, | |
413 | CXFile *file, | |
414 | unsigned *line, | |
415 | unsigned *column, | |
416 | unsigned *offset); | |
417 | ||
418 | /** | |
419 | * \brief Retrieve the file, line, column, and offset represented by | |
420 | * the given source location, as specified in a # line directive. | |
421 | * | |
422 | * Example: given the following source code in a file somefile.c | |
423 | * | |
424 | * \code | |
425 | * #123 "dummy.c" 1 | |
426 | * | |
427 | * static int func(void) | |
428 | * { | |
429 | * return 0; | |
430 | * } | |
431 | * \endcode | |
432 | * | |
433 | * the location information returned by this function would be | |
434 | * | |
435 | * File: dummy.c Line: 124 Column: 12 | |
436 | * | |
437 | * whereas clang_getExpansionLocation would have returned | |
438 | * | |
439 | * File: somefile.c Line: 3 Column: 12 | |
440 | * | |
441 | * \param location the location within a source file that will be decomposed | |
442 | * into its parts. | |
443 | * | |
444 | * \param filename [out] if non-NULL, will be set to the filename of the | |
445 | * source location. Note that filenames returned will be for "virtual" files, | |
446 | * which don't necessarily exist on the machine running clang - e.g. when | |
447 | * parsing preprocessed output obtained from a different environment. If | |
448 | * a non-NULL value is passed in, remember to dispose of the returned value | |
449 | * using \c clang_disposeString() once you've finished with it. For an invalid | |
450 | * source location, an empty string is returned. | |
451 | * | |
452 | * \param line [out] if non-NULL, will be set to the line number of the | |
453 | * source location. For an invalid source location, zero is returned. | |
454 | * | |
455 | * \param column [out] if non-NULL, will be set to the column number of the | |
456 | * source location. For an invalid source location, zero is returned. | |
457 | */ | |
458 | CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, | |
459 | CXString *filename, | |
460 | unsigned *line, | |
461 | unsigned *column); | |
462 | ||
463 | /** | |
464 | * \brief Legacy API to retrieve the file, line, column, and offset represented | |
465 | * by the given source location. | |
466 | * | |
467 | * This interface has been replaced by the newer interface | |
468 | * #clang_getExpansionLocation(). See that interface's documentation for | |
469 | * details. | |
470 | */ | |
471 | CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, | |
472 | CXFile *file, | |
473 | unsigned *line, | |
474 | unsigned *column, | |
475 | unsigned *offset); | |
476 | ||
477 | /** | |
478 | * \brief Retrieve the file, line, column, and offset represented by | |
479 | * the given source location. | |
480 | * | |
481 | * If the location refers into a macro instantiation, return where the | |
482 | * location was originally spelled in the source file. | |
483 | * | |
484 | * \param location the location within a source file that will be decomposed | |
485 | * into its parts. | |
486 | * | |
487 | * \param file [out] if non-NULL, will be set to the file to which the given | |
488 | * source location points. | |
489 | * | |
490 | * \param line [out] if non-NULL, will be set to the line to which the given | |
491 | * source location points. | |
492 | * | |
493 | * \param column [out] if non-NULL, will be set to the column to which the given | |
494 | * source location points. | |
495 | * | |
496 | * \param offset [out] if non-NULL, will be set to the offset into the | |
497 | * buffer to which the given source location points. | |
498 | */ | |
499 | CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, | |
500 | CXFile *file, | |
501 | unsigned *line, | |
502 | unsigned *column, | |
503 | unsigned *offset); | |
504 | ||
505 | /** | |
506 | * \brief Retrieve a source location representing the first character within a | |
507 | * source range. | |
508 | */ | |
509 | CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); | |
510 | ||
511 | /** | |
512 | * \brief Retrieve a source location representing the last character within a | |
513 | * source range. | |
514 | */ | |
515 | CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); | |
516 | ||
517 | /** | |
518 | * @} | |
519 | */ | |
520 | ||
521 | /** | |
522 | * \defgroup CINDEX_DIAG Diagnostic reporting | |
523 | * | |
524 | * @{ | |
525 | */ | |
526 | ||
527 | /** | |
528 | * \brief Describes the severity of a particular diagnostic. | |
529 | */ | |
530 | enum CXDiagnosticSeverity { | |
531 | /** | |
532 | * \brief A diagnostic that has been suppressed, e.g., by a command-line | |
533 | * option. | |
534 | */ | |
535 | CXDiagnostic_Ignored = 0, | |
536 | ||
537 | /** | |
538 | * \brief This diagnostic is a note that should be attached to the | |
539 | * previous (non-note) diagnostic. | |
540 | */ | |
541 | CXDiagnostic_Note = 1, | |
542 | ||
543 | /** | |
544 | * \brief This diagnostic indicates suspicious code that may not be | |
545 | * wrong. | |
546 | */ | |
547 | CXDiagnostic_Warning = 2, | |
548 | ||
549 | /** | |
550 | * \brief This diagnostic indicates that the code is ill-formed. | |
551 | */ | |
552 | CXDiagnostic_Error = 3, | |
553 | ||
554 | /** | |
555 | * \brief This diagnostic indicates that the code is ill-formed such | |
556 | * that future parser recovery is unlikely to produce useful | |
557 | * results. | |
558 | */ | |
559 | CXDiagnostic_Fatal = 4 | |
560 | }; | |
561 | ||
562 | /** | |
563 | * \brief A single diagnostic, containing the diagnostic's severity, | |
564 | * location, text, source ranges, and fix-it hints. | |
565 | */ | |
566 | typedef void *CXDiagnostic; | |
567 | ||
568 | /** | |
569 | * \brief A group of CXDiagnostics. | |
570 | */ | |
571 | typedef void *CXDiagnosticSet; | |
572 | ||
573 | /** | |
574 | * \brief Determine the number of diagnostics in a CXDiagnosticSet. | |
575 | */ | |
576 | CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); | |
577 | ||
578 | /** | |
579 | * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet. | |
580 | * | |
581 | * \param Diags the CXDiagnosticSet to query. | |
582 | * \param Index the zero-based diagnostic number to retrieve. | |
583 | * | |
584 | * \returns the requested diagnostic. This diagnostic must be freed | |
585 | * via a call to \c clang_disposeDiagnostic(). | |
586 | */ | |
587 | CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, | |
588 | unsigned Index); | |
589 | ||
590 | ||
591 | /** | |
592 | * \brief Describes the kind of error that occurred (if any) in a call to | |
593 | * \c clang_loadDiagnostics. | |
594 | */ | |
595 | enum CXLoadDiag_Error { | |
596 | /** | |
597 | * \brief Indicates that no error occurred. | |
598 | */ | |
599 | CXLoadDiag_None = 0, | |
600 | ||
601 | /** | |
602 | * \brief Indicates that an unknown error occurred while attempting to | |
603 | * deserialize diagnostics. | |
604 | */ | |
605 | CXLoadDiag_Unknown = 1, | |
606 | ||
607 | /** | |
608 | * \brief Indicates that the file containing the serialized diagnostics | |
609 | * could not be opened. | |
610 | */ | |
611 | CXLoadDiag_CannotLoad = 2, | |
612 | ||
613 | /** | |
614 | * \brief Indicates that the serialized diagnostics file is invalid or | |
615 | * corrupt. | |
616 | */ | |
617 | CXLoadDiag_InvalidFile = 3 | |
618 | }; | |
619 | ||
620 | /** | |
621 | * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode | |
622 | * file. | |
623 | * | |
624 | * \param file The name of the file to deserialize. | |
625 | * \param error A pointer to a enum value recording if there was a problem | |
626 | * deserializing the diagnostics. | |
627 | * \param errorString A pointer to a CXString for recording the error string | |
628 | * if the file was not successfully loaded. | |
629 | * | |
630 | * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These | |
631 | * diagnostics should be released using clang_disposeDiagnosticSet(). | |
632 | */ | |
633 | CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file, | |
634 | enum CXLoadDiag_Error *error, | |
635 | CXString *errorString); | |
636 | ||
637 | /** | |
638 | * \brief Release a CXDiagnosticSet and all of its contained diagnostics. | |
639 | */ | |
640 | CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); | |
641 | ||
642 | /** | |
643 | * \brief Retrieve the child diagnostics of a CXDiagnostic. | |
644 | * | |
645 | * This CXDiagnosticSet does not need to be released by | |
646 | * clang_diposeDiagnosticSet. | |
647 | */ | |
648 | CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); | |
649 | ||
650 | /** | |
651 | * \brief Determine the number of diagnostics produced for the given | |
652 | * translation unit. | |
653 | */ | |
654 | CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); | |
655 | ||
656 | /** | |
657 | * \brief Retrieve a diagnostic associated with the given translation unit. | |
658 | * | |
659 | * \param Unit the translation unit to query. | |
660 | * \param Index the zero-based diagnostic number to retrieve. | |
661 | * | |
662 | * \returns the requested diagnostic. This diagnostic must be freed | |
663 | * via a call to \c clang_disposeDiagnostic(). | |
664 | */ | |
665 | CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, | |
666 | unsigned Index); | |
667 | ||
668 | /** | |
669 | * \brief Retrieve the complete set of diagnostics associated with a | |
670 | * translation unit. | |
671 | * | |
672 | * \param Unit the translation unit to query. | |
673 | */ | |
674 | CINDEX_LINKAGE CXDiagnosticSet | |
675 | clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); | |
676 | ||
677 | /** | |
678 | * \brief Destroy a diagnostic. | |
679 | */ | |
680 | CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); | |
681 | ||
682 | /** | |
683 | * \brief Options to control the display of diagnostics. | |
684 | * | |
685 | * The values in this enum are meant to be combined to customize the | |
686 | * behavior of \c clang_displayDiagnostic(). | |
687 | */ | |
688 | enum CXDiagnosticDisplayOptions { | |
689 | /** | |
690 | * \brief Display the source-location information where the | |
691 | * diagnostic was located. | |
692 | * | |
693 | * When set, diagnostics will be prefixed by the file, line, and | |
694 | * (optionally) column to which the diagnostic refers. For example, | |
695 | * | |
696 | * \code | |
697 | * test.c:28: warning: extra tokens at end of #endif directive | |
698 | * \endcode | |
699 | * | |
700 | * This option corresponds to the clang flag \c -fshow-source-location. | |
701 | */ | |
702 | CXDiagnostic_DisplaySourceLocation = 0x01, | |
703 | ||
704 | /** | |
705 | * \brief If displaying the source-location information of the | |
706 | * diagnostic, also include the column number. | |
707 | * | |
708 | * This option corresponds to the clang flag \c -fshow-column. | |
709 | */ | |
710 | CXDiagnostic_DisplayColumn = 0x02, | |
711 | ||
712 | /** | |
713 | * \brief If displaying the source-location information of the | |
714 | * diagnostic, also include information about source ranges in a | |
715 | * machine-parsable format. | |
716 | * | |
717 | * This option corresponds to the clang flag | |
718 | * \c -fdiagnostics-print-source-range-info. | |
719 | */ | |
720 | CXDiagnostic_DisplaySourceRanges = 0x04, | |
721 | ||
722 | /** | |
723 | * \brief Display the option name associated with this diagnostic, if any. | |
724 | * | |
725 | * The option name displayed (e.g., -Wconversion) will be placed in brackets | |
726 | * after the diagnostic text. This option corresponds to the clang flag | |
727 | * \c -fdiagnostics-show-option. | |
728 | */ | |
729 | CXDiagnostic_DisplayOption = 0x08, | |
730 | ||
731 | /** | |
732 | * \brief Display the category number associated with this diagnostic, if any. | |
733 | * | |
734 | * The category number is displayed within brackets after the diagnostic text. | |
735 | * This option corresponds to the clang flag | |
736 | * \c -fdiagnostics-show-category=id. | |
737 | */ | |
738 | CXDiagnostic_DisplayCategoryId = 0x10, | |
739 | ||
740 | /** | |
741 | * \brief Display the category name associated with this diagnostic, if any. | |
742 | * | |
743 | * The category name is displayed within brackets after the diagnostic text. | |
744 | * This option corresponds to the clang flag | |
745 | * \c -fdiagnostics-show-category=name. | |
746 | */ | |
747 | CXDiagnostic_DisplayCategoryName = 0x20 | |
748 | }; | |
749 | ||
750 | /** | |
751 | * \brief Format the given diagnostic in a manner that is suitable for display. | |
752 | * | |
753 | * This routine will format the given diagnostic to a string, rendering | |
754 | * the diagnostic according to the various options given. The | |
755 | * \c clang_defaultDiagnosticDisplayOptions() function returns the set of | |
756 | * options that most closely mimics the behavior of the clang compiler. | |
757 | * | |
758 | * \param Diagnostic The diagnostic to print. | |
759 | * | |
760 | * \param Options A set of options that control the diagnostic display, | |
761 | * created by combining \c CXDiagnosticDisplayOptions values. | |
762 | * | |
763 | * \returns A new string containing for formatted diagnostic. | |
764 | */ | |
765 | CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, | |
766 | unsigned Options); | |
767 | ||
768 | /** | |
769 | * \brief Retrieve the set of display options most similar to the | |
770 | * default behavior of the clang compiler. | |
771 | * | |
772 | * \returns A set of display options suitable for use with \c | |
773 | * clang_displayDiagnostic(). | |
774 | */ | |
775 | CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); | |
776 | ||
777 | /** | |
778 | * \brief Determine the severity of the given diagnostic. | |
779 | */ | |
780 | CINDEX_LINKAGE enum CXDiagnosticSeverity | |
781 | clang_getDiagnosticSeverity(CXDiagnostic); | |
782 | ||
783 | /** | |
784 | * \brief Retrieve the source location of the given diagnostic. | |
785 | * | |
786 | * This location is where Clang would print the caret ('^') when | |
787 | * displaying the diagnostic on the command line. | |
788 | */ | |
789 | CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); | |
790 | ||
791 | /** | |
792 | * \brief Retrieve the text of the given diagnostic. | |
793 | */ | |
794 | CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); | |
795 | ||
796 | /** | |
797 | * \brief Retrieve the name of the command-line option that enabled this | |
798 | * diagnostic. | |
799 | * | |
800 | * \param Diag The diagnostic to be queried. | |
801 | * | |
802 | * \param Disable If non-NULL, will be set to the option that disables this | |
803 | * diagnostic (if any). | |
804 | * | |
805 | * \returns A string that contains the command-line option used to enable this | |
806 | * warning, such as "-Wconversion" or "-pedantic". | |
807 | */ | |
808 | CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, | |
809 | CXString *Disable); | |
810 | ||
811 | /** | |
812 | * \brief Retrieve the category number for this diagnostic. | |
813 | * | |
814 | * Diagnostics can be categorized into groups along with other, related | |
815 | * diagnostics (e.g., diagnostics under the same warning flag). This routine | |
816 | * retrieves the category number for the given diagnostic. | |
817 | * | |
818 | * \returns The number of the category that contains this diagnostic, or zero | |
819 | * if this diagnostic is uncategorized. | |
820 | */ | |
821 | CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); | |
822 | ||
823 | /** | |
824 | * \brief Retrieve the name of a particular diagnostic category. This | |
825 | * is now deprecated. Use clang_getDiagnosticCategoryText() | |
826 | * instead. | |
827 | * | |
828 | * \param Category A diagnostic category number, as returned by | |
829 | * \c clang_getDiagnosticCategory(). | |
830 | * | |
831 | * \returns The name of the given diagnostic category. | |
832 | */ | |
833 | CINDEX_DEPRECATED CINDEX_LINKAGE | |
834 | CXString clang_getDiagnosticCategoryName(unsigned Category); | |
835 | ||
836 | /** | |
837 | * \brief Retrieve the diagnostic category text for a given diagnostic. | |
838 | * | |
839 | * \returns The text of the given diagnostic category. | |
840 | */ | |
841 | CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); | |
842 | ||
843 | /** | |
844 | * \brief Determine the number of source ranges associated with the given | |
845 | * diagnostic. | |
846 | */ | |
847 | CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); | |
848 | ||
849 | /** | |
850 | * \brief Retrieve a source range associated with the diagnostic. | |
851 | * | |
852 | * A diagnostic's source ranges highlight important elements in the source | |
853 | * code. On the command line, Clang displays source ranges by | |
854 | * underlining them with '~' characters. | |
855 | * | |
856 | * \param Diagnostic the diagnostic whose range is being extracted. | |
857 | * | |
858 | * \param Range the zero-based index specifying which range to | |
859 | * | |
860 | * \returns the requested source range. | |
861 | */ | |
862 | CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, | |
863 | unsigned Range); | |
864 | ||
865 | /** | |
866 | * \brief Determine the number of fix-it hints associated with the | |
867 | * given diagnostic. | |
868 | */ | |
869 | CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); | |
870 | ||
871 | /** | |
872 | * \brief Retrieve the replacement information for a given fix-it. | |
873 | * | |
874 | * Fix-its are described in terms of a source range whose contents | |
875 | * should be replaced by a string. This approach generalizes over | |
876 | * three kinds of operations: removal of source code (the range covers | |
877 | * the code to be removed and the replacement string is empty), | |
878 | * replacement of source code (the range covers the code to be | |
879 | * replaced and the replacement string provides the new code), and | |
880 | * insertion (both the start and end of the range point at the | |
881 | * insertion location, and the replacement string provides the text to | |
882 | * insert). | |
883 | * | |
884 | * \param Diagnostic The diagnostic whose fix-its are being queried. | |
885 | * | |
886 | * \param FixIt The zero-based index of the fix-it. | |
887 | * | |
888 | * \param ReplacementRange The source range whose contents will be | |
889 | * replaced with the returned replacement string. Note that source | |
890 | * ranges are half-open ranges [a, b), so the source code should be | |
891 | * replaced from a and up to (but not including) b. | |
892 | * | |
893 | * \returns A string containing text that should be replace the source | |
894 | * code indicated by the \c ReplacementRange. | |
895 | */ | |
896 | CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, | |
897 | unsigned FixIt, | |
898 | CXSourceRange *ReplacementRange); | |
899 | ||
900 | /** | |
901 | * @} | |
902 | */ | |
903 | ||
904 | /** | |
905 | * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation | |
906 | * | |
907 | * The routines in this group provide the ability to create and destroy | |
908 | * translation units from files, either by parsing the contents of the files or | |
909 | * by reading in a serialized representation of a translation unit. | |
910 | * | |
911 | * @{ | |
912 | */ | |
913 | ||
914 | /** | |
915 | * \brief Get the original translation unit source file name. | |
916 | */ | |
917 | CINDEX_LINKAGE CXString | |
918 | clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); | |
919 | ||
920 | /** | |
921 | * \brief Return the CXTranslationUnit for a given source file and the provided | |
922 | * command line arguments one would pass to the compiler. | |
923 | * | |
924 | * Note: The 'source_filename' argument is optional. If the caller provides a | |
925 | * NULL pointer, the name of the source file is expected to reside in the | |
926 | * specified command line arguments. | |
927 | * | |
928 | * Note: When encountered in 'clang_command_line_args', the following options | |
929 | * are ignored: | |
930 | * | |
931 | * '-c' | |
932 | * '-emit-ast' | |
933 | * '-fsyntax-only' | |
934 | * '-o \<output file>' (both '-o' and '\<output file>' are ignored) | |
935 | * | |
936 | * \param CIdx The index object with which the translation unit will be | |
937 | * associated. | |
938 | * | |
939 | * \param source_filename The name of the source file to load, or NULL if the | |
940 | * source file is included in \p clang_command_line_args. | |
941 | * | |
942 | * \param num_clang_command_line_args The number of command-line arguments in | |
943 | * \p clang_command_line_args. | |
944 | * | |
945 | * \param clang_command_line_args The command-line arguments that would be | |
946 | * passed to the \c clang executable if it were being invoked out-of-process. | |
947 | * These command-line options will be parsed and will affect how the translation | |
948 | * unit is parsed. Note that the following options are ignored: '-c', | |
949 | * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. | |
950 | * | |
951 | * \param num_unsaved_files the number of unsaved file entries in \p | |
952 | * unsaved_files. | |
953 | * | |
954 | * \param unsaved_files the files that have not yet been saved to disk | |
955 | * but may be required for code completion, including the contents of | |
956 | * those files. The contents and name of these files (as specified by | |
957 | * CXUnsavedFile) are copied when necessary, so the client only needs to | |
958 | * guarantee their validity until the call to this function returns. | |
959 | */ | |
960 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( | |
961 | CXIndex CIdx, | |
962 | const char *source_filename, | |
963 | int num_clang_command_line_args, | |
964 | const char * const *clang_command_line_args, | |
965 | unsigned num_unsaved_files, | |
966 | struct CXUnsavedFile *unsaved_files); | |
967 | ||
968 | /** | |
969 | * \brief Create a translation unit from an AST file (-emit-ast). | |
970 | */ | |
971 | CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, | |
972 | const char *ast_filename); | |
973 | ||
974 | /** | |
975 | * \brief Flags that control the creation of translation units. | |
976 | * | |
977 | * The enumerators in this enumeration type are meant to be bitwise | |
978 | * ORed together to specify which options should be used when | |
979 | * constructing the translation unit. | |
980 | */ | |
981 | enum CXTranslationUnit_Flags { | |
982 | /** | |
983 | * \brief Used to indicate that no special translation-unit options are | |
984 | * needed. | |
985 | */ | |
986 | CXTranslationUnit_None = 0x0, | |
987 | ||
988 | /** | |
989 | * \brief Used to indicate that the parser should construct a "detailed" | |
990 | * preprocessing record, including all macro definitions and instantiations. | |
991 | * | |
992 | * Constructing a detailed preprocessing record requires more memory | |
993 | * and time to parse, since the information contained in the record | |
994 | * is usually not retained. However, it can be useful for | |
995 | * applications that require more detailed information about the | |
996 | * behavior of the preprocessor. | |
997 | */ | |
998 | CXTranslationUnit_DetailedPreprocessingRecord = 0x01, | |
999 | ||
1000 | /** | |
1001 | * \brief Used to indicate that the translation unit is incomplete. | |
1002 | * | |
1003 | * When a translation unit is considered "incomplete", semantic | |
1004 | * analysis that is typically performed at the end of the | |
1005 | * translation unit will be suppressed. For example, this suppresses | |
1006 | * the completion of tentative declarations in C and of | |
1007 | * instantiation of implicitly-instantiation function templates in | |
1008 | * C++. This option is typically used when parsing a header with the | |
1009 | * intent of producing a precompiled header. | |
1010 | */ | |
1011 | CXTranslationUnit_Incomplete = 0x02, | |
1012 | ||
1013 | /** | |
1014 | * \brief Used to indicate that the translation unit should be built with an | |
1015 | * implicit precompiled header for the preamble. | |
1016 | * | |
1017 | * An implicit precompiled header is used as an optimization when a | |
1018 | * particular translation unit is likely to be reparsed many times | |
1019 | * when the sources aren't changing that often. In this case, an | |
1020 | * implicit precompiled header will be built containing all of the | |
1021 | * initial includes at the top of the main file (what we refer to as | |
1022 | * the "preamble" of the file). In subsequent parses, if the | |
1023 | * preamble or the files in it have not changed, \c | |
1024 | * clang_reparseTranslationUnit() will re-use the implicit | |
1025 | * precompiled header to improve parsing performance. | |
1026 | */ | |
1027 | CXTranslationUnit_PrecompiledPreamble = 0x04, | |
1028 | ||
1029 | /** | |
1030 | * \brief Used to indicate that the translation unit should cache some | |
1031 | * code-completion results with each reparse of the source file. | |
1032 | * | |
1033 | * Caching of code-completion results is a performance optimization that | |
1034 | * introduces some overhead to reparsing but improves the performance of | |
1035 | * code-completion operations. | |
1036 | */ | |
1037 | CXTranslationUnit_CacheCompletionResults = 0x08, | |
1038 | /** | |
1039 | * \brief DEPRECATED: Enable precompiled preambles in C++. | |
1040 | * | |
1041 | * Note: this is a *temporary* option that is available only while | |
1042 | * we are testing C++ precompiled preamble support. It is deprecated. | |
1043 | */ | |
1044 | CXTranslationUnit_CXXPrecompiledPreamble = 0x10, | |
1045 | ||
1046 | /** | |
1047 | * \brief DEPRECATED: Enabled chained precompiled preambles in C++. | |
1048 | * | |
1049 | * Note: this is a *temporary* option that is available only while | |
1050 | * we are testing C++ precompiled preamble support. It is deprecated. | |
1051 | */ | |
1052 | CXTranslationUnit_CXXChainedPCH = 0x20, | |
1053 | ||
1054 | /** | |
1055 | * \brief Used to indicate that function/method bodies should be skipped while | |
1056 | * parsing. | |
1057 | * | |
1058 | * This option can be used to search for declarations/definitions while | |
1059 | * ignoring the usages. | |
1060 | */ | |
1061 | CXTranslationUnit_SkipFunctionBodies = 0x40, | |
1062 | ||
1063 | /** | |
1064 | * \brief Used to indicate that brief documentation comments should be | |
1065 | * included into the set of code completions returned from this translation | |
1066 | * unit. | |
1067 | */ | |
1068 | CXTranslationUnit_IncludeBriefCommentsInCodeCompletion = 0x80 | |
1069 | }; | |
1070 | ||
1071 | /** | |
1072 | * \brief Returns the set of flags that is suitable for parsing a translation | |
1073 | * unit that is being edited. | |
1074 | * | |
1075 | * The set of flags returned provide options for \c clang_parseTranslationUnit() | |
1076 | * to indicate that the translation unit is likely to be reparsed many times, | |
1077 | * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly | |
1078 | * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag | |
1079 | * set contains an unspecified set of optimizations (e.g., the precompiled | |
1080 | * preamble) geared toward improving the performance of these routines. The | |
1081 | * set of optimizations enabled may change from one version to the next. | |
1082 | */ | |
1083 | CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); | |
1084 | ||
1085 | /** | |
1086 | * \brief Parse the given source file and the translation unit corresponding | |
1087 | * to that file. | |
1088 | * | |
1089 | * This routine is the main entry point for the Clang C API, providing the | |
1090 | * ability to parse a source file into a translation unit that can then be | |
1091 | * queried by other functions in the API. This routine accepts a set of | |
1092 | * command-line arguments so that the compilation can be configured in the same | |
1093 | * way that the compiler is configured on the command line. | |
1094 | * | |
1095 | * \param CIdx The index object with which the translation unit will be | |
1096 | * associated. | |
1097 | * | |
1098 | * \param source_filename The name of the source file to load, or NULL if the | |
1099 | * source file is included in \p command_line_args. | |
1100 | * | |
1101 | * \param command_line_args The command-line arguments that would be | |
1102 | * passed to the \c clang executable if it were being invoked out-of-process. | |
1103 | * These command-line options will be parsed and will affect how the translation | |
1104 | * unit is parsed. Note that the following options are ignored: '-c', | |
1105 | * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. | |
1106 | * | |
1107 | * \param num_command_line_args The number of command-line arguments in | |
1108 | * \p command_line_args. | |
1109 | * | |
1110 | * \param unsaved_files the files that have not yet been saved to disk | |
1111 | * but may be required for parsing, including the contents of | |
1112 | * those files. The contents and name of these files (as specified by | |
1113 | * CXUnsavedFile) are copied when necessary, so the client only needs to | |
1114 | * guarantee their validity until the call to this function returns. | |
1115 | * | |
1116 | * \param num_unsaved_files the number of unsaved file entries in \p | |
1117 | * unsaved_files. | |
1118 | * | |
1119 | * \param options A bitmask of options that affects how the translation unit | |
1120 | * is managed but not its compilation. This should be a bitwise OR of the | |
1121 | * CXTranslationUnit_XXX flags. | |
1122 | * | |
1123 | * \returns A new translation unit describing the parsed code and containing | |
1124 | * any diagnostics produced by the compiler. If there is a failure from which | |
1125 | * the compiler cannot recover, returns NULL. | |
1126 | */ | |
1127 | CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx, | |
1128 | const char *source_filename, | |
1129 | const char * const *command_line_args, | |
1130 | int num_command_line_args, | |
1131 | struct CXUnsavedFile *unsaved_files, | |
1132 | unsigned num_unsaved_files, | |
1133 | unsigned options); | |
1134 | ||
1135 | /** | |
1136 | * \brief Flags that control how translation units are saved. | |
1137 | * | |
1138 | * The enumerators in this enumeration type are meant to be bitwise | |
1139 | * ORed together to specify which options should be used when | |
1140 | * saving the translation unit. | |
1141 | */ | |
1142 | enum CXSaveTranslationUnit_Flags { | |
1143 | /** | |
1144 | * \brief Used to indicate that no special saving options are needed. | |
1145 | */ | |
1146 | CXSaveTranslationUnit_None = 0x0 | |
1147 | }; | |
1148 | ||
1149 | /** | |
1150 | * \brief Returns the set of flags that is suitable for saving a translation | |
1151 | * unit. | |
1152 | * | |
1153 | * The set of flags returned provide options for | |
1154 | * \c clang_saveTranslationUnit() by default. The returned flag | |
1155 | * set contains an unspecified set of options that save translation units with | |
1156 | * the most commonly-requested data. | |
1157 | */ | |
1158 | CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU); | |
1159 | ||
1160 | /** | |
1161 | * \brief Describes the kind of error that occurred (if any) in a call to | |
1162 | * \c clang_saveTranslationUnit(). | |
1163 | */ | |
1164 | enum CXSaveError { | |
1165 | /** | |
1166 | * \brief Indicates that no error occurred while saving a translation unit. | |
1167 | */ | |
1168 | CXSaveError_None = 0, | |
1169 | ||
1170 | /** | |
1171 | * \brief Indicates that an unknown error occurred while attempting to save | |
1172 | * the file. | |
1173 | * | |
1174 | * This error typically indicates that file I/O failed when attempting to | |
1175 | * write the file. | |
1176 | */ | |
1177 | CXSaveError_Unknown = 1, | |
1178 | ||
1179 | /** | |
1180 | * \brief Indicates that errors during translation prevented this attempt | |
1181 | * to save the translation unit. | |
1182 | * | |
1183 | * Errors that prevent the translation unit from being saved can be | |
1184 | * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic(). | |
1185 | */ | |
1186 | CXSaveError_TranslationErrors = 2, | |
1187 | ||
1188 | /** | |
1189 | * \brief Indicates that the translation unit to be saved was somehow | |
1190 | * invalid (e.g., NULL). | |
1191 | */ | |
1192 | CXSaveError_InvalidTU = 3 | |
1193 | }; | |
1194 | ||
1195 | /** | |
1196 | * \brief Saves a translation unit into a serialized representation of | |
1197 | * that translation unit on disk. | |
1198 | * | |
1199 | * Any translation unit that was parsed without error can be saved | |
1200 | * into a file. The translation unit can then be deserialized into a | |
1201 | * new \c CXTranslationUnit with \c clang_createTranslationUnit() or, | |
1202 | * if it is an incomplete translation unit that corresponds to a | |
1203 | * header, used as a precompiled header when parsing other translation | |
1204 | * units. | |
1205 | * | |
1206 | * \param TU The translation unit to save. | |
1207 | * | |
1208 | * \param FileName The file to which the translation unit will be saved. | |
1209 | * | |
1210 | * \param options A bitmask of options that affects how the translation unit | |
1211 | * is saved. This should be a bitwise OR of the | |
1212 | * CXSaveTranslationUnit_XXX flags. | |
1213 | * | |
1214 | * \returns A value that will match one of the enumerators of the CXSaveError | |
1215 | * enumeration. Zero (CXSaveError_None) indicates that the translation unit was | |
1216 | * saved successfully, while a non-zero value indicates that a problem occurred. | |
1217 | */ | |
1218 | CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, | |
1219 | const char *FileName, | |
1220 | unsigned options); | |
1221 | ||
1222 | /** | |
1223 | * \brief Destroy the specified CXTranslationUnit object. | |
1224 | */ | |
1225 | CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); | |
1226 | ||
1227 | /** | |
1228 | * \brief Flags that control the reparsing of translation units. | |
1229 | * | |
1230 | * The enumerators in this enumeration type are meant to be bitwise | |
1231 | * ORed together to specify which options should be used when | |
1232 | * reparsing the translation unit. | |
1233 | */ | |
1234 | enum CXReparse_Flags { | |
1235 | /** | |
1236 | * \brief Used to indicate that no special reparsing options are needed. | |
1237 | */ | |
1238 | CXReparse_None = 0x0 | |
1239 | }; | |
1240 | ||
1241 | /** | |
1242 | * \brief Returns the set of flags that is suitable for reparsing a translation | |
1243 | * unit. | |
1244 | * | |
1245 | * The set of flags returned provide options for | |
1246 | * \c clang_reparseTranslationUnit() by default. The returned flag | |
1247 | * set contains an unspecified set of optimizations geared toward common uses | |
1248 | * of reparsing. The set of optimizations enabled may change from one version | |
1249 | * to the next. | |
1250 | */ | |
1251 | CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); | |
1252 | ||
1253 | /** | |
1254 | * \brief Reparse the source files that produced this translation unit. | |
1255 | * | |
1256 | * This routine can be used to re-parse the source files that originally | |
1257 | * created the given translation unit, for example because those source files | |
1258 | * have changed (either on disk or as passed via \p unsaved_files). The | |
1259 | * source code will be reparsed with the same command-line options as it | |
1260 | * was originally parsed. | |
1261 | * | |
1262 | * Reparsing a translation unit invalidates all cursors and source locations | |
1263 | * that refer into that translation unit. This makes reparsing a translation | |
1264 | * unit semantically equivalent to destroying the translation unit and then | |
1265 | * creating a new translation unit with the same command-line arguments. | |
1266 | * However, it may be more efficient to reparse a translation | |
1267 | * unit using this routine. | |
1268 | * | |
1269 | * \param TU The translation unit whose contents will be re-parsed. The | |
1270 | * translation unit must originally have been built with | |
1271 | * \c clang_createTranslationUnitFromSourceFile(). | |
1272 | * | |
1273 | * \param num_unsaved_files The number of unsaved file entries in \p | |
1274 | * unsaved_files. | |
1275 | * | |
1276 | * \param unsaved_files The files that have not yet been saved to disk | |
1277 | * but may be required for parsing, including the contents of | |
1278 | * those files. The contents and name of these files (as specified by | |
1279 | * CXUnsavedFile) are copied when necessary, so the client only needs to | |
1280 | * guarantee their validity until the call to this function returns. | |
1281 | * | |
1282 | * \param options A bitset of options composed of the flags in CXReparse_Flags. | |
1283 | * The function \c clang_defaultReparseOptions() produces a default set of | |
1284 | * options recommended for most uses, based on the translation unit. | |
1285 | * | |
1286 | * \returns 0 if the sources could be reparsed. A non-zero value will be | |
1287 | * returned if reparsing was impossible, such that the translation unit is | |
1288 | * invalid. In such cases, the only valid call for \p TU is | |
1289 | * \c clang_disposeTranslationUnit(TU). | |
1290 | */ | |
1291 | CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, | |
1292 | unsigned num_unsaved_files, | |
1293 | struct CXUnsavedFile *unsaved_files, | |
1294 | unsigned options); | |
1295 | ||
1296 | /** | |
1297 | * \brief Categorizes how memory is being used by a translation unit. | |
1298 | */ | |
1299 | enum CXTUResourceUsageKind { | |
1300 | CXTUResourceUsage_AST = 1, | |
1301 | CXTUResourceUsage_Identifiers = 2, | |
1302 | CXTUResourceUsage_Selectors = 3, | |
1303 | CXTUResourceUsage_GlobalCompletionResults = 4, | |
1304 | CXTUResourceUsage_SourceManagerContentCache = 5, | |
1305 | CXTUResourceUsage_AST_SideTables = 6, | |
1306 | CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7, | |
1307 | CXTUResourceUsage_SourceManager_Membuffer_MMap = 8, | |
1308 | CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9, | |
1309 | CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10, | |
1310 | CXTUResourceUsage_Preprocessor = 11, | |
1311 | CXTUResourceUsage_PreprocessingRecord = 12, | |
1312 | CXTUResourceUsage_SourceManager_DataStructures = 13, | |
1313 | CXTUResourceUsage_Preprocessor_HeaderSearch = 14, | |
1314 | CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST, | |
1315 | CXTUResourceUsage_MEMORY_IN_BYTES_END = | |
1316 | CXTUResourceUsage_Preprocessor_HeaderSearch, | |
1317 | ||
1318 | CXTUResourceUsage_First = CXTUResourceUsage_AST, | |
1319 | CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch | |
1320 | }; | |
1321 | ||
1322 | /** | |
1323 | * \brief Returns the human-readable null-terminated C string that represents | |
1324 | * the name of the memory category. This string should never be freed. | |
1325 | */ | |
1326 | CINDEX_LINKAGE | |
1327 | const char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind); | |
1328 | ||
1329 | typedef struct CXTUResourceUsageEntry { | |
1330 | /* \brief The memory usage category. */ | |
1331 | enum CXTUResourceUsageKind kind; | |
1332 | /* \brief Amount of resources used. | |
1333 | The units will depend on the resource kind. */ | |
1334 | unsigned long amount; | |
1335 | } CXTUResourceUsageEntry; | |
1336 | ||
1337 | /** | |
1338 | * \brief The memory usage of a CXTranslationUnit, broken into categories. | |
1339 | */ | |
1340 | typedef struct CXTUResourceUsage { | |
1341 | /* \brief Private data member, used for queries. */ | |
1342 | void *data; | |
1343 | ||
1344 | /* \brief The number of entries in the 'entries' array. */ | |
1345 | unsigned numEntries; | |
1346 | ||
1347 | /* \brief An array of key-value pairs, representing the breakdown of memory | |
1348 | usage. */ | |
1349 | CXTUResourceUsageEntry *entries; | |
1350 | ||
1351 | } CXTUResourceUsage; | |
1352 | ||
1353 | /** | |
1354 | * \brief Return the memory usage of a translation unit. This object | |
1355 | * should be released with clang_disposeCXTUResourceUsage(). | |
1356 | */ | |
1357 | CINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU); | |
1358 | ||
1359 | CINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage); | |
1360 | ||
1361 | /** | |
1362 | * @} | |
1363 | */ | |
1364 | ||
1365 | /** | |
1366 | * \brief Describes the kind of entity that a cursor refers to. | |
1367 | */ | |
1368 | enum CXCursorKind { | |
1369 | /* Declarations */ | |
1370 | /** | |
1371 | * \brief A declaration whose specific kind is not exposed via this | |
1372 | * interface. | |
1373 | * | |
1374 | * Unexposed declarations have the same operations as any other kind | |
1375 | * of declaration; one can extract their location information, | |
1376 | * spelling, find their definitions, etc. However, the specific kind | |
1377 | * of the declaration is not reported. | |
1378 | */ | |
1379 | CXCursor_UnexposedDecl = 1, | |
1380 | /** \brief A C or C++ struct. */ | |
1381 | CXCursor_StructDecl = 2, | |
1382 | /** \brief A C or C++ union. */ | |
1383 | CXCursor_UnionDecl = 3, | |
1384 | /** \brief A C++ class. */ | |
1385 | CXCursor_ClassDecl = 4, | |
1386 | /** \brief An enumeration. */ | |
1387 | CXCursor_EnumDecl = 5, | |
1388 | /** | |
1389 | * \brief A field (in C) or non-static data member (in C++) in a | |
1390 | * struct, union, or C++ class. | |
1391 | */ | |
1392 | CXCursor_FieldDecl = 6, | |
1393 | /** \brief An enumerator constant. */ | |
1394 | CXCursor_EnumConstantDecl = 7, | |
1395 | /** \brief A function. */ | |
1396 | CXCursor_FunctionDecl = 8, | |
1397 | /** \brief A variable. */ | |
1398 | CXCursor_VarDecl = 9, | |
1399 | /** \brief A function or method parameter. */ | |
1400 | CXCursor_ParmDecl = 10, | |
1401 | /** \brief An Objective-C \@interface. */ | |
1402 | CXCursor_ObjCInterfaceDecl = 11, | |
1403 | /** \brief An Objective-C \@interface for a category. */ | |
1404 | CXCursor_ObjCCategoryDecl = 12, | |
1405 | /** \brief An Objective-C \@protocol declaration. */ | |
1406 | CXCursor_ObjCProtocolDecl = 13, | |
1407 | /** \brief An Objective-C \@property declaration. */ | |
1408 | CXCursor_ObjCPropertyDecl = 14, | |
1409 | /** \brief An Objective-C instance variable. */ | |
1410 | CXCursor_ObjCIvarDecl = 15, | |
1411 | /** \brief An Objective-C instance method. */ | |
1412 | CXCursor_ObjCInstanceMethodDecl = 16, | |
1413 | /** \brief An Objective-C class method. */ | |
1414 | CXCursor_ObjCClassMethodDecl = 17, | |
1415 | /** \brief An Objective-C \@implementation. */ | |
1416 | CXCursor_ObjCImplementationDecl = 18, | |
1417 | /** \brief An Objective-C \@implementation for a category. */ | |
1418 | CXCursor_ObjCCategoryImplDecl = 19, | |
1419 | /** \brief A typedef */ | |
1420 | CXCursor_TypedefDecl = 20, | |
1421 | /** \brief A C++ class method. */ | |
1422 | CXCursor_CXXMethod = 21, | |
1423 | /** \brief A C++ namespace. */ | |
1424 | CXCursor_Namespace = 22, | |
1425 | /** \brief A linkage specification, e.g. 'extern "C"'. */ | |
1426 | CXCursor_LinkageSpec = 23, | |
1427 | /** \brief A C++ constructor. */ | |
1428 | CXCursor_Constructor = 24, | |
1429 | /** \brief A C++ destructor. */ | |
1430 | CXCursor_Destructor = 25, | |
1431 | /** \brief A C++ conversion function. */ | |
1432 | CXCursor_ConversionFunction = 26, | |
1433 | /** \brief A C++ template type parameter. */ | |
1434 | CXCursor_TemplateTypeParameter = 27, | |
1435 | /** \brief A C++ non-type template parameter. */ | |
1436 | CXCursor_NonTypeTemplateParameter = 28, | |
1437 | /** \brief A C++ template template parameter. */ | |
1438 | CXCursor_TemplateTemplateParameter = 29, | |
1439 | /** \brief A C++ function template. */ | |
1440 | CXCursor_FunctionTemplate = 30, | |
1441 | /** \brief A C++ class template. */ | |
1442 | CXCursor_ClassTemplate = 31, | |
1443 | /** \brief A C++ class template partial specialization. */ | |
1444 | CXCursor_ClassTemplatePartialSpecialization = 32, | |
1445 | /** \brief A C++ namespace alias declaration. */ | |
1446 | CXCursor_NamespaceAlias = 33, | |
1447 | /** \brief A C++ using directive. */ | |
1448 | CXCursor_UsingDirective = 34, | |
1449 | /** \brief A C++ using declaration. */ | |
1450 | CXCursor_UsingDeclaration = 35, | |
1451 | /** \brief A C++ alias declaration */ | |
1452 | CXCursor_TypeAliasDecl = 36, | |
1453 | /** \brief An Objective-C \@synthesize definition. */ | |
1454 | CXCursor_ObjCSynthesizeDecl = 37, | |
1455 | /** \brief An Objective-C \@dynamic definition. */ | |
1456 | CXCursor_ObjCDynamicDecl = 38, | |
1457 | /** \brief An access specifier. */ | |
1458 | CXCursor_CXXAccessSpecifier = 39, | |
1459 | ||
1460 | CXCursor_FirstDecl = CXCursor_UnexposedDecl, | |
1461 | CXCursor_LastDecl = CXCursor_CXXAccessSpecifier, | |
1462 | ||
1463 | /* References */ | |
1464 | CXCursor_FirstRef = 40, /* Decl references */ | |
1465 | CXCursor_ObjCSuperClassRef = 40, | |
1466 | CXCursor_ObjCProtocolRef = 41, | |
1467 | CXCursor_ObjCClassRef = 42, | |
1468 | /** | |
1469 | * \brief A reference to a type declaration. | |
1470 | * | |
1471 | * A type reference occurs anywhere where a type is named but not | |
1472 | * declared. For example, given: | |
1473 | * | |
1474 | * \code | |
1475 | * typedef unsigned size_type; | |
1476 | * size_type size; | |
1477 | * \endcode | |
1478 | * | |
1479 | * The typedef is a declaration of size_type (CXCursor_TypedefDecl), | |
1480 | * while the type of the variable "size" is referenced. The cursor | |
1481 | * referenced by the type of size is the typedef for size_type. | |
1482 | */ | |
1483 | CXCursor_TypeRef = 43, | |
1484 | CXCursor_CXXBaseSpecifier = 44, | |
1485 | /** | |
1486 | * \brief A reference to a class template, function template, template | |
1487 | * template parameter, or class template partial specialization. | |
1488 | */ | |
1489 | CXCursor_TemplateRef = 45, | |
1490 | /** | |
1491 | * \brief A reference to a namespace or namespace alias. | |
1492 | */ | |
1493 | CXCursor_NamespaceRef = 46, | |
1494 | /** | |
1495 | * \brief A reference to a member of a struct, union, or class that occurs in | |
1496 | * some non-expression context, e.g., a designated initializer. | |
1497 | */ | |
1498 | CXCursor_MemberRef = 47, | |
1499 | /** | |
1500 | * \brief A reference to a labeled statement. | |
1501 | * | |
1502 | * This cursor kind is used to describe the jump to "start_over" in the | |
1503 | * goto statement in the following example: | |
1504 | * | |
1505 | * \code | |
1506 | * start_over: | |
1507 | * ++counter; | |
1508 | * | |
1509 | * goto start_over; | |
1510 | * \endcode | |
1511 | * | |
1512 | * A label reference cursor refers to a label statement. | |
1513 | */ | |
1514 | CXCursor_LabelRef = 48, | |
1515 | ||
1516 | /** | |
1517 | * \brief A reference to a set of overloaded functions or function templates | |
1518 | * that has not yet been resolved to a specific function or function template. | |
1519 | * | |
1520 | * An overloaded declaration reference cursor occurs in C++ templates where | |
1521 | * a dependent name refers to a function. For example: | |
1522 | * | |
1523 | * \code | |
1524 | * template<typename T> void swap(T&, T&); | |
1525 | * | |
1526 | * struct X { ... }; | |
1527 | * void swap(X&, X&); | |
1528 | * | |
1529 | * template<typename T> | |
1530 | * void reverse(T* first, T* last) { | |
1531 | * while (first < last - 1) { | |
1532 | * swap(*first, *--last); | |
1533 | * ++first; | |
1534 | * } | |
1535 | * } | |
1536 | * | |
1537 | * struct Y { }; | |
1538 | * void swap(Y&, Y&); | |
1539 | * \endcode | |
1540 | * | |
1541 | * Here, the identifier "swap" is associated with an overloaded declaration | |
1542 | * reference. In the template definition, "swap" refers to either of the two | |
1543 | * "swap" functions declared above, so both results will be available. At | |
1544 | * instantiation time, "swap" may also refer to other functions found via | |
1545 | * argument-dependent lookup (e.g., the "swap" function at the end of the | |
1546 | * example). | |
1547 | * | |
1548 | * The functions \c clang_getNumOverloadedDecls() and | |
1549 | * \c clang_getOverloadedDecl() can be used to retrieve the definitions | |
1550 | * referenced by this cursor. | |
1551 | */ | |
1552 | CXCursor_OverloadedDeclRef = 49, | |
1553 | ||
1554 | /** | |
1555 | * \brief A reference to a variable that occurs in some non-expression | |
1556 | * context, e.g., a C++ lambda capture list. | |
1557 | */ | |
1558 | CXCursor_VariableRef = 50, | |
1559 | ||
1560 | CXCursor_LastRef = CXCursor_VariableRef, | |
1561 | ||
1562 | /* Error conditions */ | |
1563 | CXCursor_FirstInvalid = 70, | |
1564 | CXCursor_InvalidFile = 70, | |
1565 | CXCursor_NoDeclFound = 71, | |
1566 | CXCursor_NotImplemented = 72, | |
1567 | CXCursor_InvalidCode = 73, | |
1568 | CXCursor_LastInvalid = CXCursor_InvalidCode, | |
1569 | ||
1570 | /* Expressions */ | |
1571 | CXCursor_FirstExpr = 100, | |
1572 | ||
1573 | /** | |
1574 | * \brief An expression whose specific kind is not exposed via this | |
1575 | * interface. | |
1576 | * | |
1577 | * Unexposed expressions have the same operations as any other kind | |
1578 | * of expression; one can extract their location information, | |
1579 | * spelling, children, etc. However, the specific kind of the | |
1580 | * expression is not reported. | |
1581 | */ | |
1582 | CXCursor_UnexposedExpr = 100, | |
1583 | ||
1584 | /** | |
1585 | * \brief An expression that refers to some value declaration, such | |
1586 | * as a function, varible, or enumerator. | |
1587 | */ | |
1588 | CXCursor_DeclRefExpr = 101, | |
1589 | ||
1590 | /** | |
1591 | * \brief An expression that refers to a member of a struct, union, | |
1592 | * class, Objective-C class, etc. | |
1593 | */ | |
1594 | CXCursor_MemberRefExpr = 102, | |
1595 | ||
1596 | /** \brief An expression that calls a function. */ | |
1597 | CXCursor_CallExpr = 103, | |
1598 | ||
1599 | /** \brief An expression that sends a message to an Objective-C | |
1600 | object or class. */ | |
1601 | CXCursor_ObjCMessageExpr = 104, | |
1602 | ||
1603 | /** \brief An expression that represents a block literal. */ | |
1604 | CXCursor_BlockExpr = 105, | |
1605 | ||
1606 | /** \brief An integer literal. | |
1607 | */ | |
1608 | CXCursor_IntegerLiteral = 106, | |
1609 | ||
1610 | /** \brief A floating point number literal. | |
1611 | */ | |
1612 | CXCursor_FloatingLiteral = 107, | |
1613 | ||
1614 | /** \brief An imaginary number literal. | |
1615 | */ | |
1616 | CXCursor_ImaginaryLiteral = 108, | |
1617 | ||
1618 | /** \brief A string literal. | |
1619 | */ | |
1620 | CXCursor_StringLiteral = 109, | |
1621 | ||
1622 | /** \brief A character literal. | |
1623 | */ | |
1624 | CXCursor_CharacterLiteral = 110, | |
1625 | ||
1626 | /** \brief A parenthesized expression, e.g. "(1)". | |
1627 | * | |
1628 | * This AST node is only formed if full location information is requested. | |
1629 | */ | |
1630 | CXCursor_ParenExpr = 111, | |
1631 | ||
1632 | /** \brief This represents the unary-expression's (except sizeof and | |
1633 | * alignof). | |
1634 | */ | |
1635 | CXCursor_UnaryOperator = 112, | |
1636 | ||
1637 | /** \brief [C99 6.5.2.1] Array Subscripting. | |
1638 | */ | |
1639 | CXCursor_ArraySubscriptExpr = 113, | |
1640 | ||
1641 | /** \brief A builtin binary operation expression such as "x + y" or | |
1642 | * "x <= y". | |
1643 | */ | |
1644 | CXCursor_BinaryOperator = 114, | |
1645 | ||
1646 | /** \brief Compound assignment such as "+=". | |
1647 | */ | |
1648 | CXCursor_CompoundAssignOperator = 115, | |
1649 | ||
1650 | /** \brief The ?: ternary operator. | |
1651 | */ | |
1652 | CXCursor_ConditionalOperator = 116, | |
1653 | ||
1654 | /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++ | |
1655 | * (C++ [expr.cast]), which uses the syntax (Type)expr. | |
1656 | * | |
1657 | * For example: (int)f. | |
1658 | */ | |
1659 | CXCursor_CStyleCastExpr = 117, | |
1660 | ||
1661 | /** \brief [C99 6.5.2.5] | |
1662 | */ | |
1663 | CXCursor_CompoundLiteralExpr = 118, | |
1664 | ||
1665 | /** \brief Describes an C or C++ initializer list. | |
1666 | */ | |
1667 | CXCursor_InitListExpr = 119, | |
1668 | ||
1669 | /** \brief The GNU address of label extension, representing &&label. | |
1670 | */ | |
1671 | CXCursor_AddrLabelExpr = 120, | |
1672 | ||
1673 | /** \brief This is the GNU Statement Expression extension: ({int X=4; X;}) | |
1674 | */ | |
1675 | CXCursor_StmtExpr = 121, | |
1676 | ||
1677 | /** \brief Represents a C11 generic selection. | |
1678 | */ | |
1679 | CXCursor_GenericSelectionExpr = 122, | |
1680 | ||
1681 | /** \brief Implements the GNU __null extension, which is a name for a null | |
1682 | * pointer constant that has integral type (e.g., int or long) and is the same | |
1683 | * size and alignment as a pointer. | |
1684 | * | |
1685 | * The __null extension is typically only used by system headers, which define | |
1686 | * NULL as __null in C++ rather than using 0 (which is an integer that may not | |
1687 | * match the size of a pointer). | |
1688 | */ | |
1689 | CXCursor_GNUNullExpr = 123, | |
1690 | ||
1691 | /** \brief C++'s static_cast<> expression. | |
1692 | */ | |
1693 | CXCursor_CXXStaticCastExpr = 124, | |
1694 | ||
1695 | /** \brief C++'s dynamic_cast<> expression. | |
1696 | */ | |
1697 | CXCursor_CXXDynamicCastExpr = 125, | |
1698 | ||
1699 | /** \brief C++'s reinterpret_cast<> expression. | |
1700 | */ | |
1701 | CXCursor_CXXReinterpretCastExpr = 126, | |
1702 | ||
1703 | /** \brief C++'s const_cast<> expression. | |
1704 | */ | |
1705 | CXCursor_CXXConstCastExpr = 127, | |
1706 | ||
1707 | /** \brief Represents an explicit C++ type conversion that uses "functional" | |
1708 | * notion (C++ [expr.type.conv]). | |
1709 | * | |
1710 | * Example: | |
1711 | * \code | |
1712 | * x = int(0.5); | |
1713 | * \endcode | |
1714 | */ | |
1715 | CXCursor_CXXFunctionalCastExpr = 128, | |
1716 | ||
1717 | /** \brief A C++ typeid expression (C++ [expr.typeid]). | |
1718 | */ | |
1719 | CXCursor_CXXTypeidExpr = 129, | |
1720 | ||
1721 | /** \brief [C++ 2.13.5] C++ Boolean Literal. | |
1722 | */ | |
1723 | CXCursor_CXXBoolLiteralExpr = 130, | |
1724 | ||
1725 | /** \brief [C++0x 2.14.7] C++ Pointer Literal. | |
1726 | */ | |
1727 | CXCursor_CXXNullPtrLiteralExpr = 131, | |
1728 | ||
1729 | /** \brief Represents the "this" expression in C++ | |
1730 | */ | |
1731 | CXCursor_CXXThisExpr = 132, | |
1732 | ||
1733 | /** \brief [C++ 15] C++ Throw Expression. | |
1734 | * | |
1735 | * This handles 'throw' and 'throw' assignment-expression. When | |
1736 | * assignment-expression isn't present, Op will be null. | |
1737 | */ | |
1738 | CXCursor_CXXThrowExpr = 133, | |
1739 | ||
1740 | /** \brief A new expression for memory allocation and constructor calls, e.g: | |
1741 | * "new CXXNewExpr(foo)". | |
1742 | */ | |
1743 | CXCursor_CXXNewExpr = 134, | |
1744 | ||
1745 | /** \brief A delete expression for memory deallocation and destructor calls, | |
1746 | * e.g. "delete[] pArray". | |
1747 | */ | |
1748 | CXCursor_CXXDeleteExpr = 135, | |
1749 | ||
1750 | /** \brief A unary expression. | |
1751 | */ | |
1752 | CXCursor_UnaryExpr = 136, | |
1753 | ||
1754 | /** \brief An Objective-C string literal i.e. @"foo". | |
1755 | */ | |
1756 | CXCursor_ObjCStringLiteral = 137, | |
1757 | ||
1758 | /** \brief An Objective-C \@encode expression. | |
1759 | */ | |
1760 | CXCursor_ObjCEncodeExpr = 138, | |
1761 | ||
1762 | /** \brief An Objective-C \@selector expression. | |
1763 | */ | |
1764 | CXCursor_ObjCSelectorExpr = 139, | |
1765 | ||
1766 | /** \brief An Objective-C \@protocol expression. | |
1767 | */ | |
1768 | CXCursor_ObjCProtocolExpr = 140, | |
1769 | ||
1770 | /** \brief An Objective-C "bridged" cast expression, which casts between | |
1771 | * Objective-C pointers and C pointers, transferring ownership in the process. | |
1772 | * | |
1773 | * \code | |
1774 | * NSString *str = (__bridge_transfer NSString *)CFCreateString(); | |
1775 | * \endcode | |
1776 | */ | |
1777 | CXCursor_ObjCBridgedCastExpr = 141, | |
1778 | ||
1779 | /** \brief Represents a C++0x pack expansion that produces a sequence of | |
1780 | * expressions. | |
1781 | * | |
1782 | * A pack expansion expression contains a pattern (which itself is an | |
1783 | * expression) followed by an ellipsis. For example: | |
1784 | * | |
1785 | * \code | |
1786 | * template<typename F, typename ...Types> | |
1787 | * void forward(F f, Types &&...args) { | |
1788 | * f(static_cast<Types&&>(args)...); | |
1789 | * } | |
1790 | * \endcode | |
1791 | */ | |
1792 | CXCursor_PackExpansionExpr = 142, | |
1793 | ||
1794 | /** \brief Represents an expression that computes the length of a parameter | |
1795 | * pack. | |
1796 | * | |
1797 | * \code | |
1798 | * template<typename ...Types> | |
1799 | * struct count { | |
1800 | * static const unsigned value = sizeof...(Types); | |
1801 | * }; | |
1802 | * \endcode | |
1803 | */ | |
1804 | CXCursor_SizeOfPackExpr = 143, | |
1805 | ||
1806 | /* \brief Represents a C++ lambda expression that produces a local function | |
1807 | * object. | |
1808 | * | |
1809 | * \code | |
1810 | * void abssort(float *x, unsigned N) { | |
1811 | * std::sort(x, x + N, | |
1812 | * [](float a, float b) { | |
1813 | * return std::abs(a) < std::abs(b); | |
1814 | * }); | |
1815 | * } | |
1816 | * \endcode | |
1817 | */ | |
1818 | CXCursor_LambdaExpr = 144, | |
1819 | ||
1820 | /** \brief Objective-c Boolean Literal. | |
1821 | */ | |
1822 | CXCursor_ObjCBoolLiteralExpr = 145, | |
1823 | ||
1824 | CXCursor_LastExpr = CXCursor_ObjCBoolLiteralExpr, | |
1825 | ||
1826 | /* Statements */ | |
1827 | CXCursor_FirstStmt = 200, | |
1828 | /** | |
1829 | * \brief A statement whose specific kind is not exposed via this | |
1830 | * interface. | |
1831 | * | |
1832 | * Unexposed statements have the same operations as any other kind of | |
1833 | * statement; one can extract their location information, spelling, | |
1834 | * children, etc. However, the specific kind of the statement is not | |
1835 | * reported. | |
1836 | */ | |
1837 | CXCursor_UnexposedStmt = 200, | |
1838 | ||
1839 | /** \brief A labelled statement in a function. | |
1840 | * | |
1841 | * This cursor kind is used to describe the "start_over:" label statement in | |
1842 | * the following example: | |
1843 | * | |
1844 | * \code | |
1845 | * start_over: | |
1846 | * ++counter; | |
1847 | * \endcode | |
1848 | * | |
1849 | */ | |
1850 | CXCursor_LabelStmt = 201, | |
1851 | ||
1852 | /** \brief A group of statements like { stmt stmt }. | |
1853 | * | |
1854 | * This cursor kind is used to describe compound statements, e.g. function | |
1855 | * bodies. | |
1856 | */ | |
1857 | CXCursor_CompoundStmt = 202, | |
1858 | ||
1859 | /** \brief A case statment. | |
1860 | */ | |
1861 | CXCursor_CaseStmt = 203, | |
1862 | ||
1863 | /** \brief A default statement. | |
1864 | */ | |
1865 | CXCursor_DefaultStmt = 204, | |
1866 | ||
1867 | /** \brief An if statement | |
1868 | */ | |
1869 | CXCursor_IfStmt = 205, | |
1870 | ||
1871 | /** \brief A switch statement. | |
1872 | */ | |
1873 | CXCursor_SwitchStmt = 206, | |
1874 | ||
1875 | /** \brief A while statement. | |
1876 | */ | |
1877 | CXCursor_WhileStmt = 207, | |
1878 | ||
1879 | /** \brief A do statement. | |
1880 | */ | |
1881 | CXCursor_DoStmt = 208, | |
1882 | ||
1883 | /** \brief A for statement. | |
1884 | */ | |
1885 | CXCursor_ForStmt = 209, | |
1886 | ||
1887 | /** \brief A goto statement. | |
1888 | */ | |
1889 | CXCursor_GotoStmt = 210, | |
1890 | ||
1891 | /** \brief An indirect goto statement. | |
1892 | */ | |
1893 | CXCursor_IndirectGotoStmt = 211, | |
1894 | ||
1895 | /** \brief A continue statement. | |
1896 | */ | |
1897 | CXCursor_ContinueStmt = 212, | |
1898 | ||
1899 | /** \brief A break statement. | |
1900 | */ | |
1901 | CXCursor_BreakStmt = 213, | |
1902 | ||
1903 | /** \brief A return statement. | |
1904 | */ | |
1905 | CXCursor_ReturnStmt = 214, | |
1906 | ||
1907 | /** \brief A GCC inline assembly statement extension. | |
1908 | */ | |
1909 | CXCursor_GCCAsmStmt = 215, | |
1910 | CXCursor_AsmStmt = CXCursor_GCCAsmStmt, | |
1911 | ||
1912 | /** \brief Objective-C's overall \@try-\@catch-\@finally statement. | |
1913 | */ | |
1914 | CXCursor_ObjCAtTryStmt = 216, | |
1915 | ||
1916 | /** \brief Objective-C's \@catch statement. | |
1917 | */ | |
1918 | CXCursor_ObjCAtCatchStmt = 217, | |
1919 | ||
1920 | /** \brief Objective-C's \@finally statement. | |
1921 | */ | |
1922 | CXCursor_ObjCAtFinallyStmt = 218, | |
1923 | ||
1924 | /** \brief Objective-C's \@throw statement. | |
1925 | */ | |
1926 | CXCursor_ObjCAtThrowStmt = 219, | |
1927 | ||
1928 | /** \brief Objective-C's \@synchronized statement. | |
1929 | */ | |
1930 | CXCursor_ObjCAtSynchronizedStmt = 220, | |
1931 | ||
1932 | /** \brief Objective-C's autorelease pool statement. | |
1933 | */ | |
1934 | CXCursor_ObjCAutoreleasePoolStmt = 221, | |
1935 | ||
1936 | /** \brief Objective-C's collection statement. | |
1937 | */ | |
1938 | CXCursor_ObjCForCollectionStmt = 222, | |
1939 | ||
1940 | /** \brief C++'s catch statement. | |
1941 | */ | |
1942 | CXCursor_CXXCatchStmt = 223, | |
1943 | ||
1944 | /** \brief C++'s try statement. | |
1945 | */ | |
1946 | CXCursor_CXXTryStmt = 224, | |
1947 | ||
1948 | /** \brief C++'s for (* : *) statement. | |
1949 | */ | |
1950 | CXCursor_CXXForRangeStmt = 225, | |
1951 | ||
1952 | /** \brief Windows Structured Exception Handling's try statement. | |
1953 | */ | |
1954 | CXCursor_SEHTryStmt = 226, | |
1955 | ||
1956 | /** \brief Windows Structured Exception Handling's except statement. | |
1957 | */ | |
1958 | CXCursor_SEHExceptStmt = 227, | |
1959 | ||
1960 | /** \brief Windows Structured Exception Handling's finally statement. | |
1961 | */ | |
1962 | CXCursor_SEHFinallyStmt = 228, | |
1963 | ||
1964 | /** \brief A MS inline assembly statement extension. | |
1965 | */ | |
1966 | CXCursor_MSAsmStmt = 229, | |
1967 | ||
1968 | /** \brief The null satement ";": C99 6.8.3p3. | |
1969 | * | |
1970 | * This cursor kind is used to describe the null statement. | |
1971 | */ | |
1972 | CXCursor_NullStmt = 230, | |
1973 | ||
1974 | /** \brief Adaptor class for mixing declarations with statements and | |
1975 | * expressions. | |
1976 | */ | |
1977 | CXCursor_DeclStmt = 231, | |
1978 | ||
1979 | CXCursor_LastStmt = CXCursor_DeclStmt, | |
1980 | ||
1981 | /** | |
1982 | * \brief Cursor that represents the translation unit itself. | |
1983 | * | |
1984 | * The translation unit cursor exists primarily to act as the root | |
1985 | * cursor for traversing the contents of a translation unit. | |
1986 | */ | |
1987 | CXCursor_TranslationUnit = 300, | |
1988 | ||
1989 | /* Attributes */ | |
1990 | CXCursor_FirstAttr = 400, | |
1991 | /** | |
1992 | * \brief An attribute whose specific kind is not exposed via this | |
1993 | * interface. | |
1994 | */ | |
1995 | CXCursor_UnexposedAttr = 400, | |
1996 | ||
1997 | CXCursor_IBActionAttr = 401, | |
1998 | CXCursor_IBOutletAttr = 402, | |
1999 | CXCursor_IBOutletCollectionAttr = 403, | |
2000 | CXCursor_CXXFinalAttr = 404, | |
2001 | CXCursor_CXXOverrideAttr = 405, | |
2002 | CXCursor_AnnotateAttr = 406, | |
2003 | CXCursor_AsmLabelAttr = 407, | |
2004 | CXCursor_LastAttr = CXCursor_AsmLabelAttr, | |
2005 | ||
2006 | /* Preprocessing */ | |
2007 | CXCursor_PreprocessingDirective = 500, | |
2008 | CXCursor_MacroDefinition = 501, | |
2009 | CXCursor_MacroExpansion = 502, | |
2010 | CXCursor_MacroInstantiation = CXCursor_MacroExpansion, | |
2011 | CXCursor_InclusionDirective = 503, | |
2012 | CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective, | |
2013 | CXCursor_LastPreprocessing = CXCursor_InclusionDirective | |
2014 | }; | |
2015 | ||
2016 | /** | |
2017 | * \brief A cursor representing some element in the abstract syntax tree for | |
2018 | * a translation unit. | |
2019 | * | |
2020 | * The cursor abstraction unifies the different kinds of entities in a | |
2021 | * program--declaration, statements, expressions, references to declarations, | |
2022 | * etc.--under a single "cursor" abstraction with a common set of operations. | |
2023 | * Common operation for a cursor include: getting the physical location in | |
2024 | * a source file where the cursor points, getting the name associated with a | |
2025 | * cursor, and retrieving cursors for any child nodes of a particular cursor. | |
2026 | * | |
2027 | * Cursors can be produced in two specific ways. | |
2028 | * clang_getTranslationUnitCursor() produces a cursor for a translation unit, | |
2029 | * from which one can use clang_visitChildren() to explore the rest of the | |
2030 | * translation unit. clang_getCursor() maps from a physical source location | |
2031 | * to the entity that resides at that location, allowing one to map from the | |
2032 | * source code into the AST. | |
2033 | */ | |
2034 | typedef struct { | |
2035 | enum CXCursorKind kind; | |
2036 | int xdata; | |
2037 | void *data[3]; | |
2038 | } CXCursor; | |
2039 | ||
2040 | /** | |
2041 | * \brief A comment AST node. | |
2042 | */ | |
2043 | typedef struct { | |
2044 | const void *ASTNode; | |
2045 | CXTranslationUnit TranslationUnit; | |
2046 | } CXComment; | |
2047 | ||
2048 | /** | |
2049 | * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations | |
2050 | * | |
2051 | * @{ | |
2052 | */ | |
2053 | ||
2054 | /** | |
2055 | * \brief Retrieve the NULL cursor, which represents no entity. | |
2056 | */ | |
2057 | CINDEX_LINKAGE CXCursor clang_getNullCursor(void); | |
2058 | ||
2059 | /** | |
2060 | * \brief Retrieve the cursor that represents the given translation unit. | |
2061 | * | |
2062 | * The translation unit cursor can be used to start traversing the | |
2063 | * various declarations within the given translation unit. | |
2064 | */ | |
2065 | CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); | |
2066 | ||
2067 | /** | |
2068 | * \brief Determine whether two cursors are equivalent. | |
2069 | */ | |
2070 | CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); | |
2071 | ||
2072 | /** | |
2073 | * \brief Returns non-zero if \p cursor is null. | |
2074 | */ | |
2075 | CINDEX_LINKAGE int clang_Cursor_isNull(CXCursor cursor); | |
2076 | ||
2077 | /** | |
2078 | * \brief Compute a hash value for the given cursor. | |
2079 | */ | |
2080 | CINDEX_LINKAGE unsigned clang_hashCursor(CXCursor); | |
2081 | ||
2082 | /** | |
2083 | * \brief Retrieve the kind of the given cursor. | |
2084 | */ | |
2085 | CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); | |
2086 | ||
2087 | /** | |
2088 | * \brief Determine whether the given cursor kind represents a declaration. | |
2089 | */ | |
2090 | CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); | |
2091 | ||
2092 | /** | |
2093 | * \brief Determine whether the given cursor kind represents a simple | |
2094 | * reference. | |
2095 | * | |
2096 | * Note that other kinds of cursors (such as expressions) can also refer to | |
2097 | * other cursors. Use clang_getCursorReferenced() to determine whether a | |
2098 | * particular cursor refers to another entity. | |
2099 | */ | |
2100 | CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); | |
2101 | ||
2102 | /** | |
2103 | * \brief Determine whether the given cursor kind represents an expression. | |
2104 | */ | |
2105 | CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); | |
2106 | ||
2107 | /** | |
2108 | * \brief Determine whether the given cursor kind represents a statement. | |
2109 | */ | |
2110 | CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); | |
2111 | ||
2112 | /** | |
2113 | * \brief Determine whether the given cursor kind represents an attribute. | |
2114 | */ | |
2115 | CINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind); | |
2116 | ||
2117 | /** | |
2118 | * \brief Determine whether the given cursor kind represents an invalid | |
2119 | * cursor. | |
2120 | */ | |
2121 | CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); | |
2122 | ||
2123 | /** | |
2124 | * \brief Determine whether the given cursor kind represents a translation | |
2125 | * unit. | |
2126 | */ | |
2127 | CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); | |
2128 | ||
2129 | /*** | |
2130 | * \brief Determine whether the given cursor represents a preprocessing | |
2131 | * element, such as a preprocessor directive or macro instantiation. | |
2132 | */ | |
2133 | CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); | |
2134 | ||
2135 | /*** | |
2136 | * \brief Determine whether the given cursor represents a currently | |
2137 | * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). | |
2138 | */ | |
2139 | CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); | |
2140 | ||
2141 | /** | |
2142 | * \brief Describe the linkage of the entity referred to by a cursor. | |
2143 | */ | |
2144 | enum CXLinkageKind { | |
2145 | /** \brief This value indicates that no linkage information is available | |
2146 | * for a provided CXCursor. */ | |
2147 | CXLinkage_Invalid, | |
2148 | /** | |
2149 | * \brief This is the linkage for variables, parameters, and so on that | |
2150 | * have automatic storage. This covers normal (non-extern) local variables. | |
2151 | */ | |
2152 | CXLinkage_NoLinkage, | |
2153 | /** \brief This is the linkage for static variables and static functions. */ | |
2154 | CXLinkage_Internal, | |
2155 | /** \brief This is the linkage for entities with external linkage that live | |
2156 | * in C++ anonymous namespaces.*/ | |
2157 | CXLinkage_UniqueExternal, | |
2158 | /** \brief This is the linkage for entities with true, external linkage. */ | |
2159 | CXLinkage_External | |
2160 | }; | |
2161 | ||
2162 | /** | |
2163 | * \brief Determine the linkage of the entity referred to by a given cursor. | |
2164 | */ | |
2165 | CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); | |
2166 | ||
2167 | /** | |
2168 | * \brief Determine the availability of the entity that this cursor refers to, | |
2169 | * taking the current target platform into account. | |
2170 | * | |
2171 | * \param cursor The cursor to query. | |
2172 | * | |
2173 | * \returns The availability of the cursor. | |
2174 | */ | |
2175 | CINDEX_LINKAGE enum CXAvailabilityKind | |
2176 | clang_getCursorAvailability(CXCursor cursor); | |
2177 | ||
2178 | /** | |
2179 | * Describes the availability of a given entity on a particular platform, e.g., | |
2180 | * a particular class might only be available on Mac OS 10.7 or newer. | |
2181 | */ | |
2182 | typedef struct CXPlatformAvailability { | |
2183 | /** | |
2184 | * \brief A string that describes the platform for which this structure | |
2185 | * provides availability information. | |
2186 | * | |
2187 | * Possible values are "ios" or "macosx". | |
2188 | */ | |
2189 | CXString Platform; | |
2190 | /** | |
2191 | * \brief The version number in which this entity was introduced. | |
2192 | */ | |
2193 | CXVersion Introduced; | |
2194 | /** | |
2195 | * \brief The version number in which this entity was deprecated (but is | |
2196 | * still available). | |
2197 | */ | |
2198 | CXVersion Deprecated; | |
2199 | /** | |
2200 | * \brief The version number in which this entity was obsoleted, and therefore | |
2201 | * is no longer available. | |
2202 | */ | |
2203 | CXVersion Obsoleted; | |
2204 | /** | |
2205 | * \brief Whether the entity is unconditionally unavailable on this platform. | |
2206 | */ | |
2207 | int Unavailable; | |
2208 | /** | |
2209 | * \brief An optional message to provide to a user of this API, e.g., to | |
2210 | * suggest replacement APIs. | |
2211 | */ | |
2212 | CXString Message; | |
2213 | } CXPlatformAvailability; | |
2214 | ||
2215 | /** | |
2216 | * \brief Determine the availability of the entity that this cursor refers to | |
2217 | * on any platforms for which availability information is known. | |
2218 | * | |
2219 | * \param cursor The cursor to query. | |
2220 | * | |
2221 | * \param always_deprecated If non-NULL, will be set to indicate whether the | |
2222 | * entity is deprecated on all platforms. | |
2223 | * | |
2224 | * \param deprecated_message If non-NULL, will be set to the message text | |
2225 | * provided along with the unconditional deprecation of this entity. The client | |
2226 | * is responsible for deallocating this string. | |
2227 | * | |
2228 | * \param always_unavailable If non-NULL, will be set to indicate whether the | |
2229 | * entity is unavailable on all platforms. | |
2230 | * | |
2231 | * \param unavailable_message If non-NULL, will be set to the message text | |
2232 | * provided along with the unconditional unavailability of this entity. The | |
2233 | * client is responsible for deallocating this string. | |
2234 | * | |
2235 | * \param availability If non-NULL, an array of CXPlatformAvailability instances | |
2236 | * that will be populated with platform availability information, up to either | |
2237 | * the number of platforms for which availability information is available (as | |
2238 | * returned by this function) or \c availability_size, whichever is smaller. | |
2239 | * | |
2240 | * \param availability_size The number of elements available in the | |
2241 | * \c availability array. | |
2242 | * | |
2243 | * \returns The number of platforms (N) for which availability information is | |
2244 | * available (which is unrelated to \c availability_size). | |
2245 | * | |
2246 | * Note that the client is responsible for calling | |
2247 | * \c clang_disposeCXPlatformAvailability to free each of the | |
2248 | * platform-availability structures returned. There are | |
2249 | * \c min(N, availability_size) such structures. | |
2250 | */ | |
2251 | CINDEX_LINKAGE int | |
2252 | clang_getCursorPlatformAvailability(CXCursor cursor, | |
2253 | int *always_deprecated, | |
2254 | CXString *deprecated_message, | |
2255 | int *always_unavailable, | |
2256 | CXString *unavailable_message, | |
2257 | CXPlatformAvailability *availability, | |
2258 | int availability_size); | |
2259 | ||
2260 | /** | |
2261 | * \brief Free the memory associated with a \c CXPlatformAvailability structure. | |
2262 | */ | |
2263 | CINDEX_LINKAGE void | |
2264 | clang_disposeCXPlatformAvailability(CXPlatformAvailability *availability); | |
2265 | ||
2266 | /** | |
2267 | * \brief Describe the "language" of the entity referred to by a cursor. | |
2268 | */ | |
2269 | CINDEX_LINKAGE enum CXLanguageKind { | |
2270 | CXLanguage_Invalid = 0, | |
2271 | CXLanguage_C, | |
2272 | CXLanguage_ObjC, | |
2273 | CXLanguage_CPlusPlus | |
2274 | }; | |
2275 | ||
2276 | /** | |
2277 | * \brief Determine the "language" of the entity referred to by a given cursor. | |
2278 | */ | |
2279 | CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); | |
2280 | ||
2281 | /** | |
2282 | * \brief Returns the translation unit that a cursor originated from. | |
2283 | */ | |
2284 | CINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor); | |
2285 | ||
2286 | ||
2287 | /** | |
2288 | * \brief A fast container representing a set of CXCursors. | |
2289 | */ | |
2290 | typedef struct CXCursorSetImpl *CXCursorSet; | |
2291 | ||
2292 | /** | |
2293 | * \brief Creates an empty CXCursorSet. | |
2294 | */ | |
2295 | CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(); | |
2296 | ||
2297 | /** | |
2298 | * \brief Disposes a CXCursorSet and releases its associated memory. | |
2299 | */ | |
2300 | CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset); | |
2301 | ||
2302 | /** | |
2303 | * \brief Queries a CXCursorSet to see if it contains a specific CXCursor. | |
2304 | * | |
2305 | * \returns non-zero if the set contains the specified cursor. | |
2306 | */ | |
2307 | CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset, | |
2308 | CXCursor cursor); | |
2309 | ||
2310 | /** | |
2311 | * \brief Inserts a CXCursor into a CXCursorSet. | |
2312 | * | |
2313 | * \returns zero if the CXCursor was already in the set, and non-zero otherwise. | |
2314 | */ | |
2315 | CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, | |
2316 | CXCursor cursor); | |
2317 | ||
2318 | /** | |
2319 | * \brief Determine the semantic parent of the given cursor. | |
2320 | * | |
2321 | * The semantic parent of a cursor is the cursor that semantically contains | |
2322 | * the given \p cursor. For many declarations, the lexical and semantic parents | |
2323 | * are equivalent (the lexical parent is returned by | |
2324 | * \c clang_getCursorLexicalParent()). They diverge when declarations or | |
2325 | * definitions are provided out-of-line. For example: | |
2326 | * | |
2327 | * \code | |
2328 | * class C { | |
2329 | * void f(); | |
2330 | * }; | |
2331 | * | |
2332 | * void C::f() { } | |
2333 | * \endcode | |
2334 | * | |
2335 | * In the out-of-line definition of \c C::f, the semantic parent is the | |
2336 | * the class \c C, of which this function is a member. The lexical parent is | |
2337 | * the place where the declaration actually occurs in the source code; in this | |
2338 | * case, the definition occurs in the translation unit. In general, the | |
2339 | * lexical parent for a given entity can change without affecting the semantics | |
2340 | * of the program, and the lexical parent of different declarations of the | |
2341 | * same entity may be different. Changing the semantic parent of a declaration, | |
2342 | * on the other hand, can have a major impact on semantics, and redeclarations | |
2343 | * of a particular entity should all have the same semantic context. | |
2344 | * | |
2345 | * In the example above, both declarations of \c C::f have \c C as their | |
2346 | * semantic context, while the lexical context of the first \c C::f is \c C | |
2347 | * and the lexical context of the second \c C::f is the translation unit. | |
2348 | * | |
2349 | * For global declarations, the semantic parent is the translation unit. | |
2350 | */ | |
2351 | CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); | |
2352 | ||
2353 | /** | |
2354 | * \brief Determine the lexical parent of the given cursor. | |
2355 | * | |
2356 | * The lexical parent of a cursor is the cursor in which the given \p cursor | |
2357 | * was actually written. For many declarations, the lexical and semantic parents | |
2358 | * are equivalent (the semantic parent is returned by | |
2359 | * \c clang_getCursorSemanticParent()). They diverge when declarations or | |
2360 | * definitions are provided out-of-line. For example: | |
2361 | * | |
2362 | * \code | |
2363 | * class C { | |
2364 | * void f(); | |
2365 | * }; | |
2366 | * | |
2367 | * void C::f() { } | |
2368 | * \endcode | |
2369 | * | |
2370 | * In the out-of-line definition of \c C::f, the semantic parent is the | |
2371 | * the class \c C, of which this function is a member. The lexical parent is | |
2372 | * the place where the declaration actually occurs in the source code; in this | |
2373 | * case, the definition occurs in the translation unit. In general, the | |
2374 | * lexical parent for a given entity can change without affecting the semantics | |
2375 | * of the program, and the lexical parent of different declarations of the | |
2376 | * same entity may be different. Changing the semantic parent of a declaration, | |
2377 | * on the other hand, can have a major impact on semantics, and redeclarations | |
2378 | * of a particular entity should all have the same semantic context. | |
2379 | * | |
2380 | * In the example above, both declarations of \c C::f have \c C as their | |
2381 | * semantic context, while the lexical context of the first \c C::f is \c C | |
2382 | * and the lexical context of the second \c C::f is the translation unit. | |
2383 | * | |
2384 | * For declarations written in the global scope, the lexical parent is | |
2385 | * the translation unit. | |
2386 | */ | |
2387 | CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor); | |
2388 | ||
2389 | /** | |
2390 | * \brief Determine the set of methods that are overridden by the given | |
2391 | * method. | |
2392 | * | |
2393 | * In both Objective-C and C++, a method (aka virtual member function, | |
2394 | * in C++) can override a virtual method in a base class. For | |
2395 | * Objective-C, a method is said to override any method in the class's | |
2396 | * base class, its protocols, or its categories' protocols, that has the same | |
2397 | * selector and is of the same kind (class or instance). | |
2398 | * If no such method exists, the search continues to the class's superclass, | |
2399 | * its protocols, and its categories, and so on. A method from an Objective-C | |
2400 | * implementation is considered to override the same methods as its | |
2401 | * corresponding method in the interface. | |
2402 | * | |
2403 | * For C++, a virtual member function overrides any virtual member | |
2404 | * function with the same signature that occurs in its base | |
2405 | * classes. With multiple inheritance, a virtual member function can | |
2406 | * override several virtual member functions coming from different | |
2407 | * base classes. | |
2408 | * | |
2409 | * In all cases, this function determines the immediate overridden | |
2410 | * method, rather than all of the overridden methods. For example, if | |
2411 | * a method is originally declared in a class A, then overridden in B | |
2412 | * (which in inherits from A) and also in C (which inherited from B), | |
2413 | * then the only overridden method returned from this function when | |
2414 | * invoked on C's method will be B's method. The client may then | |
2415 | * invoke this function again, given the previously-found overridden | |
2416 | * methods, to map out the complete method-override set. | |
2417 | * | |
2418 | * \param cursor A cursor representing an Objective-C or C++ | |
2419 | * method. This routine will compute the set of methods that this | |
2420 | * method overrides. | |
2421 | * | |
2422 | * \param overridden A pointer whose pointee will be replaced with a | |
2423 | * pointer to an array of cursors, representing the set of overridden | |
2424 | * methods. If there are no overridden methods, the pointee will be | |
2425 | * set to NULL. The pointee must be freed via a call to | |
2426 | * \c clang_disposeOverriddenCursors(). | |
2427 | * | |
2428 | * \param num_overridden A pointer to the number of overridden | |
2429 | * functions, will be set to the number of overridden functions in the | |
2430 | * array pointed to by \p overridden. | |
2431 | */ | |
2432 | CINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor, | |
2433 | CXCursor **overridden, | |
2434 | unsigned *num_overridden); | |
2435 | ||
2436 | /** | |
2437 | * \brief Free the set of overridden cursors returned by \c | |
2438 | * clang_getOverriddenCursors(). | |
2439 | */ | |
2440 | CINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden); | |
2441 | ||
2442 | /** | |
2443 | * \brief Retrieve the file that is included by the given inclusion directive | |
2444 | * cursor. | |
2445 | */ | |
2446 | CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); | |
2447 | ||
2448 | /** | |
2449 | * @} | |
2450 | */ | |
2451 | ||
2452 | /** | |
2453 | * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code | |
2454 | * | |
2455 | * Cursors represent a location within the Abstract Syntax Tree (AST). These | |
2456 | * routines help map between cursors and the physical locations where the | |
2457 | * described entities occur in the source code. The mapping is provided in | |
2458 | * both directions, so one can map from source code to the AST and back. | |
2459 | * | |
2460 | * @{ | |
2461 | */ | |
2462 | ||
2463 | /** | |
2464 | * \brief Map a source location to the cursor that describes the entity at that | |
2465 | * location in the source code. | |
2466 | * | |
2467 | * clang_getCursor() maps an arbitrary source location within a translation | |
2468 | * unit down to the most specific cursor that describes the entity at that | |
2469 | * location. For example, given an expression \c x + y, invoking | |
2470 | * clang_getCursor() with a source location pointing to "x" will return the | |
2471 | * cursor for "x"; similarly for "y". If the cursor points anywhere between | |
2472 | * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() | |
2473 | * will return a cursor referring to the "+" expression. | |
2474 | * | |
2475 | * \returns a cursor representing the entity at the given source location, or | |
2476 | * a NULL cursor if no such entity can be found. | |
2477 | */ | |
2478 | CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); | |
2479 | ||
2480 | /** | |
2481 | * \brief Retrieve the physical location of the source constructor referenced | |
2482 | * by the given cursor. | |
2483 | * | |
2484 | * The location of a declaration is typically the location of the name of that | |
2485 | * declaration, where the name of that declaration would occur if it is | |
2486 | * unnamed, or some keyword that introduces that particular declaration. | |
2487 | * The location of a reference is where that reference occurs within the | |
2488 | * source code. | |
2489 | */ | |
2490 | CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); | |
2491 | ||
2492 | /** | |
2493 | * \brief Retrieve the physical extent of the source construct referenced by | |
2494 | * the given cursor. | |
2495 | * | |
2496 | * The extent of a cursor starts with the file/line/column pointing at the | |
2497 | * first character within the source construct that the cursor refers to and | |
2498 | * ends with the last character withinin that source construct. For a | |
2499 | * declaration, the extent covers the declaration itself. For a reference, | |
2500 | * the extent covers the location of the reference (e.g., where the referenced | |
2501 | * entity was actually used). | |
2502 | */ | |
2503 | CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); | |
2504 | ||
2505 | /** | |
2506 | * @} | |
2507 | */ | |
2508 | ||
2509 | /** | |
2510 | * \defgroup CINDEX_TYPES Type information for CXCursors | |
2511 | * | |
2512 | * @{ | |
2513 | */ | |
2514 | ||
2515 | /** | |
2516 | * \brief Describes the kind of type | |
2517 | */ | |
2518 | enum CXTypeKind { | |
2519 | /** | |
2520 | * \brief Reprents an invalid type (e.g., where no type is available). | |
2521 | */ | |
2522 | CXType_Invalid = 0, | |
2523 | ||
2524 | /** | |
2525 | * \brief A type whose specific kind is not exposed via this | |
2526 | * interface. | |
2527 | */ | |
2528 | CXType_Unexposed = 1, | |
2529 | ||
2530 | /* Builtin types */ | |
2531 | CXType_Void = 2, | |
2532 | CXType_Bool = 3, | |
2533 | CXType_Char_U = 4, | |
2534 | CXType_UChar = 5, | |
2535 | CXType_Char16 = 6, | |
2536 | CXType_Char32 = 7, | |
2537 | CXType_UShort = 8, | |
2538 | CXType_UInt = 9, | |
2539 | CXType_ULong = 10, | |
2540 | CXType_ULongLong = 11, | |
2541 | CXType_UInt128 = 12, | |
2542 | CXType_Char_S = 13, | |
2543 | CXType_SChar = 14, | |
2544 | CXType_WChar = 15, | |
2545 | CXType_Short = 16, | |
2546 | CXType_Int = 17, | |
2547 | CXType_Long = 18, | |
2548 | CXType_LongLong = 19, | |
2549 | CXType_Int128 = 20, | |
2550 | CXType_Float = 21, | |
2551 | CXType_Double = 22, | |
2552 | CXType_LongDouble = 23, | |
2553 | CXType_NullPtr = 24, | |
2554 | CXType_Overload = 25, | |
2555 | CXType_Dependent = 26, | |
2556 | CXType_ObjCId = 27, | |
2557 | CXType_ObjCClass = 28, | |
2558 | CXType_ObjCSel = 29, | |
2559 | CXType_FirstBuiltin = CXType_Void, | |
2560 | CXType_LastBuiltin = CXType_ObjCSel, | |
2561 | ||
2562 | CXType_Complex = 100, | |
2563 | CXType_Pointer = 101, | |
2564 | CXType_BlockPointer = 102, | |
2565 | CXType_LValueReference = 103, | |
2566 | CXType_RValueReference = 104, | |
2567 | CXType_Record = 105, | |
2568 | CXType_Enum = 106, | |
2569 | CXType_Typedef = 107, | |
2570 | CXType_ObjCInterface = 108, | |
2571 | CXType_ObjCObjectPointer = 109, | |
2572 | CXType_FunctionNoProto = 110, | |
2573 | CXType_FunctionProto = 111, | |
2574 | CXType_ConstantArray = 112, | |
2575 | CXType_Vector = 113 | |
2576 | }; | |
2577 | ||
2578 | /** | |
2579 | * \brief Describes the calling convention of a function type | |
2580 | */ | |
2581 | enum CXCallingConv { | |
2582 | CXCallingConv_Default = 0, | |
2583 | CXCallingConv_C = 1, | |
2584 | CXCallingConv_X86StdCall = 2, | |
2585 | CXCallingConv_X86FastCall = 3, | |
2586 | CXCallingConv_X86ThisCall = 4, | |
2587 | CXCallingConv_X86Pascal = 5, | |
2588 | CXCallingConv_AAPCS = 6, | |
2589 | CXCallingConv_AAPCS_VFP = 7, | |
2590 | ||
2591 | CXCallingConv_Invalid = 100, | |
2592 | CXCallingConv_Unexposed = 200 | |
2593 | }; | |
2594 | ||
2595 | ||
2596 | /** | |
2597 | * \brief The type of an element in the abstract syntax tree. | |
2598 | * | |
2599 | */ | |
2600 | typedef struct { | |
2601 | enum CXTypeKind kind; | |
2602 | void *data[2]; | |
2603 | } CXType; | |
2604 | ||
2605 | /** | |
2606 | * \brief Retrieve the type of a CXCursor (if any). | |
2607 | */ | |
2608 | CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); | |
2609 | ||
2610 | /** | |
2611 | * \brief Retrieve the underlying type of a typedef declaration. | |
2612 | * | |
2613 | * If the cursor does not reference a typedef declaration, an invalid type is | |
2614 | * returned. | |
2615 | */ | |
2616 | CINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); | |
2617 | ||
2618 | /** | |
2619 | * \brief Retrieve the integer type of an enum declaration. | |
2620 | * | |
2621 | * If the cursor does not reference an enum declaration, an invalid type is | |
2622 | * returned. | |
2623 | */ | |
2624 | CINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); | |
2625 | ||
2626 | /** | |
2627 | * \brief Retrieve the integer value of an enum constant declaration as a signed | |
2628 | * long long. | |
2629 | * | |
2630 | * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned. | |
2631 | * Since this is also potentially a valid constant value, the kind of the cursor | |
2632 | * must be verified before calling this function. | |
2633 | */ | |
2634 | CINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); | |
2635 | ||
2636 | /** | |
2637 | * \brief Retrieve the integer value of an enum constant declaration as an unsigned | |
2638 | * long long. | |
2639 | * | |
2640 | * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned. | |
2641 | * Since this is also potentially a valid constant value, the kind of the cursor | |
2642 | * must be verified before calling this function. | |
2643 | */ | |
2644 | CINDEX_LINKAGE unsigned long long clang_getEnumConstantDeclUnsignedValue(CXCursor C); | |
2645 | ||
2646 | /** | |
2647 | * \brief Retrieve the number of non-variadic arguments associated with a given | |
2648 | * cursor. | |
2649 | * | |
2650 | * If a cursor that is not a function or method is passed in, -1 is returned. | |
2651 | */ | |
2652 | CINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C); | |
2653 | ||
2654 | /** | |
2655 | * \brief Retrieve the argument cursor of a function or method. | |
2656 | * | |
2657 | * If a cursor that is not a function or method is passed in or the index | |
2658 | * exceeds the number of arguments, an invalid cursor is returned. | |
2659 | */ | |
2660 | CINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i); | |
2661 | ||
2662 | /** | |
2663 | * \brief Determine whether two CXTypes represent the same type. | |
2664 | * | |
2665 | * \returns non-zero if the CXTypes represent the same type and | |
2666 | * zero otherwise. | |
2667 | */ | |
2668 | CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); | |
2669 | ||
2670 | /** | |
2671 | * \brief Return the canonical type for a CXType. | |
2672 | * | |
2673 | * Clang's type system explicitly models typedefs and all the ways | |
2674 | * a specific type can be represented. The canonical type is the underlying | |
2675 | * type with all the "sugar" removed. For example, if 'T' is a typedef | |
2676 | * for 'int', the canonical type for 'T' would be 'int'. | |
2677 | */ | |
2678 | CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); | |
2679 | ||
2680 | /** | |
2681 | * \brief Determine whether a CXType has the "const" qualifier set, | |
2682 | * without looking through typedefs that may have added "const" at a | |
2683 | * different level. | |
2684 | */ | |
2685 | CINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T); | |
2686 | ||
2687 | /** | |
2688 | * \brief Determine whether a CXType has the "volatile" qualifier set, | |
2689 | * without looking through typedefs that may have added "volatile" at | |
2690 | * a different level. | |
2691 | */ | |
2692 | CINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T); | |
2693 | ||
2694 | /** | |
2695 | * \brief Determine whether a CXType has the "restrict" qualifier set, | |
2696 | * without looking through typedefs that may have added "restrict" at a | |
2697 | * different level. | |
2698 | */ | |
2699 | CINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T); | |
2700 | ||
2701 | /** | |
2702 | * \brief For pointer types, returns the type of the pointee. | |
2703 | */ | |
2704 | CINDEX_LINKAGE CXType clang_getPointeeType(CXType T); | |
2705 | ||
2706 | /** | |
2707 | * \brief Return the cursor for the declaration of the given type. | |
2708 | */ | |
2709 | CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); | |
2710 | ||
2711 | /** | |
2712 | * Returns the Objective-C type encoding for the specified declaration. | |
2713 | */ | |
2714 | CINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C); | |
2715 | ||
2716 | /** | |
2717 | * \brief Retrieve the spelling of a given CXTypeKind. | |
2718 | */ | |
2719 | CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); | |
2720 | ||
2721 | /** | |
2722 | * \brief Retrieve the calling convention associated with a function type. | |
2723 | * | |
2724 | * If a non-function type is passed in, CXCallingConv_Invalid is returned. | |
2725 | */ | |
2726 | CINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T); | |
2727 | ||
2728 | /** | |
2729 | * \brief Retrieve the result type associated with a function type. | |
2730 | * | |
2731 | * If a non-function type is passed in, an invalid type is returned. | |
2732 | */ | |
2733 | CINDEX_LINKAGE CXType clang_getResultType(CXType T); | |
2734 | ||
2735 | /** | |
2736 | * \brief Retrieve the number of non-variadic arguments associated with a | |
2737 | * function type. | |
2738 | * | |
2739 | * If a non-function type is passed in, -1 is returned. | |
2740 | */ | |
2741 | CINDEX_LINKAGE int clang_getNumArgTypes(CXType T); | |
2742 | ||
2743 | /** | |
2744 | * \brief Retrieve the type of an argument of a function type. | |
2745 | * | |
2746 | * If a non-function type is passed in or the function does not have enough | |
2747 | * parameters, an invalid type is returned. | |
2748 | */ | |
2749 | CINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i); | |
2750 | ||
2751 | /** | |
2752 | * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise. | |
2753 | */ | |
2754 | CINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T); | |
2755 | ||
2756 | /** | |
2757 | * \brief Retrieve the result type associated with a given cursor. | |
2758 | * | |
2759 | * This only returns a valid type if the cursor refers to a function or method. | |
2760 | */ | |
2761 | CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); | |
2762 | ||
2763 | /** | |
2764 | * \brief Return 1 if the CXType is a POD (plain old data) type, and 0 | |
2765 | * otherwise. | |
2766 | */ | |
2767 | CINDEX_LINKAGE unsigned clang_isPODType(CXType T); | |
2768 | ||
2769 | /** | |
2770 | * \brief Return the element type of an array, complex, or vector type. | |
2771 | * | |
2772 | * If a type is passed in that is not an array, complex, or vector type, | |
2773 | * an invalid type is returned. | |
2774 | */ | |
2775 | CINDEX_LINKAGE CXType clang_getElementType(CXType T); | |
2776 | ||
2777 | /** | |
2778 | * \brief Return the number of elements of an array or vector type. | |
2779 | * | |
2780 | * If a type is passed in that is not an array or vector type, | |
2781 | * -1 is returned. | |
2782 | */ | |
2783 | CINDEX_LINKAGE long long clang_getNumElements(CXType T); | |
2784 | ||
2785 | /** | |
2786 | * \brief Return the element type of an array type. | |
2787 | * | |
2788 | * If a non-array type is passed in, an invalid type is returned. | |
2789 | */ | |
2790 | CINDEX_LINKAGE CXType clang_getArrayElementType(CXType T); | |
2791 | ||
2792 | /** | |
2793 | * \brief Return the array size of a constant array. | |
2794 | * | |
2795 | * If a non-array type is passed in, -1 is returned. | |
2796 | */ | |
2797 | CINDEX_LINKAGE long long clang_getArraySize(CXType T); | |
2798 | ||
2799 | /** | |
2800 | * \brief Returns 1 if the base class specified by the cursor with kind | |
2801 | * CX_CXXBaseSpecifier is virtual. | |
2802 | */ | |
2803 | CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor); | |
2804 | ||
2805 | /** | |
2806 | * \brief Represents the C++ access control level to a base class for a | |
2807 | * cursor with kind CX_CXXBaseSpecifier. | |
2808 | */ | |
2809 | enum CX_CXXAccessSpecifier { | |
2810 | CX_CXXInvalidAccessSpecifier, | |
2811 | CX_CXXPublic, | |
2812 | CX_CXXProtected, | |
2813 | CX_CXXPrivate | |
2814 | }; | |
2815 | ||
2816 | /** | |
2817 | * \brief Returns the access control level for the C++ base specifier | |
2818 | * represented by a cursor with kind CXCursor_CXXBaseSpecifier or | |
2819 | * CXCursor_AccessSpecifier. | |
2820 | */ | |
2821 | CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor); | |
2822 | ||
2823 | /** | |
2824 | * \brief Determine the number of overloaded declarations referenced by a | |
2825 | * \c CXCursor_OverloadedDeclRef cursor. | |
2826 | * | |
2827 | * \param cursor The cursor whose overloaded declarations are being queried. | |
2828 | * | |
2829 | * \returns The number of overloaded declarations referenced by \c cursor. If it | |
2830 | * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0. | |
2831 | */ | |
2832 | CINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor); | |
2833 | ||
2834 | /** | |
2835 | * \brief Retrieve a cursor for one of the overloaded declarations referenced | |
2836 | * by a \c CXCursor_OverloadedDeclRef cursor. | |
2837 | * | |
2838 | * \param cursor The cursor whose overloaded declarations are being queried. | |
2839 | * | |
2840 | * \param index The zero-based index into the set of overloaded declarations in | |
2841 | * the cursor. | |
2842 | * | |
2843 | * \returns A cursor representing the declaration referenced by the given | |
2844 | * \c cursor at the specified \c index. If the cursor does not have an | |
2845 | * associated set of overloaded declarations, or if the index is out of bounds, | |
2846 | * returns \c clang_getNullCursor(); | |
2847 | */ | |
2848 | CINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor, | |
2849 | unsigned index); | |
2850 | ||
2851 | /** | |
2852 | * @} | |
2853 | */ | |
2854 | ||
2855 | /** | |
2856 | * \defgroup CINDEX_ATTRIBUTES Information for attributes | |
2857 | * | |
2858 | * @{ | |
2859 | */ | |
2860 | ||
2861 | ||
2862 | /** | |
2863 | * \brief For cursors representing an iboutletcollection attribute, | |
2864 | * this function returns the collection element type. | |
2865 | * | |
2866 | */ | |
2867 | CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); | |
2868 | ||
2869 | /** | |
2870 | * @} | |
2871 | */ | |
2872 | ||
2873 | /** | |
2874 | * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors | |
2875 | * | |
2876 | * These routines provide the ability to traverse the abstract syntax tree | |
2877 | * using cursors. | |
2878 | * | |
2879 | * @{ | |
2880 | */ | |
2881 | ||
2882 | /** | |
2883 | * \brief Describes how the traversal of the children of a particular | |
2884 | * cursor should proceed after visiting a particular child cursor. | |
2885 | * | |
2886 | * A value of this enumeration type should be returned by each | |
2887 | * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. | |
2888 | */ | |
2889 | enum CXChildVisitResult { | |
2890 | /** | |
2891 | * \brief Terminates the cursor traversal. | |
2892 | */ | |
2893 | CXChildVisit_Break, | |
2894 | /** | |
2895 | * \brief Continues the cursor traversal with the next sibling of | |
2896 | * the cursor just visited, without visiting its children. | |
2897 | */ | |
2898 | CXChildVisit_Continue, | |
2899 | /** | |
2900 | * \brief Recursively traverse the children of this cursor, using | |
2901 | * the same visitor and client data. | |
2902 | */ | |
2903 | CXChildVisit_Recurse | |
2904 | }; | |
2905 | ||
2906 | /** | |
2907 | * \brief Visitor invoked for each cursor found by a traversal. | |
2908 | * | |
2909 | * This visitor function will be invoked for each cursor found by | |
2910 | * clang_visitCursorChildren(). Its first argument is the cursor being | |
2911 | * visited, its second argument is the parent visitor for that cursor, | |
2912 | * and its third argument is the client data provided to | |
2913 | * clang_visitCursorChildren(). | |
2914 | * | |
2915 | * The visitor should return one of the \c CXChildVisitResult values | |
2916 | * to direct clang_visitCursorChildren(). | |
2917 | */ | |
2918 | typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, | |
2919 | CXCursor parent, | |
2920 | CXClientData client_data); | |
2921 | ||
2922 | /** | |
2923 | * \brief Visit the children of a particular cursor. | |
2924 | * | |
2925 | * This function visits all the direct children of the given cursor, | |
2926 | * invoking the given \p visitor function with the cursors of each | |
2927 | * visited child. The traversal may be recursive, if the visitor returns | |
2928 | * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if | |
2929 | * the visitor returns \c CXChildVisit_Break. | |
2930 | * | |
2931 | * \param parent the cursor whose child may be visited. All kinds of | |
2932 | * cursors can be visited, including invalid cursors (which, by | |
2933 | * definition, have no children). | |
2934 | * | |
2935 | * \param visitor the visitor function that will be invoked for each | |
2936 | * child of \p parent. | |
2937 | * | |
2938 | * \param client_data pointer data supplied by the client, which will | |
2939 | * be passed to the visitor each time it is invoked. | |
2940 | * | |
2941 | * \returns a non-zero value if the traversal was terminated | |
2942 | * prematurely by the visitor returning \c CXChildVisit_Break. | |
2943 | */ | |
2944 | CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, | |
2945 | CXCursorVisitor visitor, | |
2946 | CXClientData client_data); | |
2947 | #ifdef __has_feature | |
2948 | # if __has_feature(blocks) | |
2949 | /** | |
2950 | * \brief Visitor invoked for each cursor found by a traversal. | |
2951 | * | |
2952 | * This visitor block will be invoked for each cursor found by | |
2953 | * clang_visitChildrenWithBlock(). Its first argument is the cursor being | |
2954 | * visited, its second argument is the parent visitor for that cursor. | |
2955 | * | |
2956 | * The visitor should return one of the \c CXChildVisitResult values | |
2957 | * to direct clang_visitChildrenWithBlock(). | |
2958 | */ | |
2959 | typedef enum CXChildVisitResult | |
2960 | (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent); | |
2961 | ||
2962 | /** | |
2963 | * Visits the children of a cursor using the specified block. Behaves | |
2964 | * identically to clang_visitChildren() in all other respects. | |
2965 | */ | |
2966 | unsigned clang_visitChildrenWithBlock(CXCursor parent, | |
2967 | CXCursorVisitorBlock block); | |
2968 | # endif | |
2969 | #endif | |
2970 | ||
2971 | /** | |
2972 | * @} | |
2973 | */ | |
2974 | ||
2975 | /** | |
2976 | * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST | |
2977 | * | |
2978 | * These routines provide the ability to determine references within and | |
2979 | * across translation units, by providing the names of the entities referenced | |
2980 | * by cursors, follow reference cursors to the declarations they reference, | |
2981 | * and associate declarations with their definitions. | |
2982 | * | |
2983 | * @{ | |
2984 | */ | |
2985 | ||
2986 | /** | |
2987 | * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced | |
2988 | * by the given cursor. | |
2989 | * | |
2990 | * A Unified Symbol Resolution (USR) is a string that identifies a particular | |
2991 | * entity (function, class, variable, etc.) within a program. USRs can be | |
2992 | * compared across translation units to determine, e.g., when references in | |
2993 | * one translation refer to an entity defined in another translation unit. | |
2994 | */ | |
2995 | CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); | |
2996 | ||
2997 | /** | |
2998 | * \brief Construct a USR for a specified Objective-C class. | |
2999 | */ | |
3000 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); | |
3001 | ||
3002 | /** | |
3003 | * \brief Construct a USR for a specified Objective-C category. | |
3004 | */ | |
3005 | CINDEX_LINKAGE CXString | |
3006 | clang_constructUSR_ObjCCategory(const char *class_name, | |
3007 | const char *category_name); | |
3008 | ||
3009 | /** | |
3010 | * \brief Construct a USR for a specified Objective-C protocol. | |
3011 | */ | |
3012 | CINDEX_LINKAGE CXString | |
3013 | clang_constructUSR_ObjCProtocol(const char *protocol_name); | |
3014 | ||
3015 | ||
3016 | /** | |
3017 | * \brief Construct a USR for a specified Objective-C instance variable and | |
3018 | * the USR for its containing class. | |
3019 | */ | |
3020 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, | |
3021 | CXString classUSR); | |
3022 | ||
3023 | /** | |
3024 | * \brief Construct a USR for a specified Objective-C method and | |
3025 | * the USR for its containing class. | |
3026 | */ | |
3027 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, | |
3028 | unsigned isInstanceMethod, | |
3029 | CXString classUSR); | |
3030 | ||
3031 | /** | |
3032 | * \brief Construct a USR for a specified Objective-C property and the USR | |
3033 | * for its containing class. | |
3034 | */ | |
3035 | CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, | |
3036 | CXString classUSR); | |
3037 | ||
3038 | /** | |
3039 | * \brief Retrieve a name for the entity referenced by this cursor. | |
3040 | */ | |
3041 | CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); | |
3042 | ||
3043 | /** | |
3044 | * \brief Retrieve a range for a piece that forms the cursors spelling name. | |
3045 | * Most of the times there is only one range for the complete spelling but for | |
3046 | * objc methods and objc message expressions, there are multiple pieces for each | |
3047 | * selector identifier. | |
3048 | * | |
3049 | * \param pieceIndex the index of the spelling name piece. If this is greater | |
3050 | * than the actual number of pieces, it will return a NULL (invalid) range. | |
3051 | * | |
3052 | * \param options Reserved. | |
3053 | */ | |
3054 | CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(CXCursor, | |
3055 | unsigned pieceIndex, | |
3056 | unsigned options); | |
3057 | ||
3058 | /** | |
3059 | * \brief Retrieve the display name for the entity referenced by this cursor. | |
3060 | * | |
3061 | * The display name contains extra information that helps identify the cursor, | |
3062 | * such as the parameters of a function or template or the arguments of a | |
3063 | * class template specialization. | |
3064 | */ | |
3065 | CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); | |
3066 | ||
3067 | /** \brief For a cursor that is a reference, retrieve a cursor representing the | |
3068 | * entity that it references. | |
3069 | * | |
3070 | * Reference cursors refer to other entities in the AST. For example, an | |
3071 | * Objective-C superclass reference cursor refers to an Objective-C class. | |
3072 | * This function produces the cursor for the Objective-C class from the | |
3073 | * cursor for the superclass reference. If the input cursor is a declaration or | |
3074 | * definition, it returns that declaration or definition unchanged. | |
3075 | * Otherwise, returns the NULL cursor. | |
3076 | */ | |
3077 | CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); | |
3078 | ||
3079 | /** | |
3080 | * \brief For a cursor that is either a reference to or a declaration | |
3081 | * of some entity, retrieve a cursor that describes the definition of | |
3082 | * that entity. | |
3083 | * | |
3084 | * Some entities can be declared multiple times within a translation | |
3085 | * unit, but only one of those declarations can also be a | |
3086 | * definition. For example, given: | |
3087 | * | |
3088 | * \code | |
3089 | * int f(int, int); | |
3090 | * int g(int x, int y) { return f(x, y); } | |
3091 | * int f(int a, int b) { return a + b; } | |
3092 | * int f(int, int); | |
3093 | * \endcode | |
3094 | * | |
3095 | * there are three declarations of the function "f", but only the | |
3096 | * second one is a definition. The clang_getCursorDefinition() | |
3097 | * function will take any cursor pointing to a declaration of "f" | |
3098 | * (the first or fourth lines of the example) or a cursor referenced | |
3099 | * that uses "f" (the call to "f' inside "g") and will return a | |
3100 | * declaration cursor pointing to the definition (the second "f" | |
3101 | * declaration). | |
3102 | * | |
3103 | * If given a cursor for which there is no corresponding definition, | |
3104 | * e.g., because there is no definition of that entity within this | |
3105 | * translation unit, returns a NULL cursor. | |
3106 | */ | |
3107 | CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); | |
3108 | ||
3109 | /** | |
3110 | * \brief Determine whether the declaration pointed to by this cursor | |
3111 | * is also a definition of that entity. | |
3112 | */ | |
3113 | CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); | |
3114 | ||
3115 | /** | |
3116 | * \brief Retrieve the canonical cursor corresponding to the given cursor. | |
3117 | * | |
3118 | * In the C family of languages, many kinds of entities can be declared several | |
3119 | * times within a single translation unit. For example, a structure type can | |
3120 | * be forward-declared (possibly multiple times) and later defined: | |
3121 | * | |
3122 | * \code | |
3123 | * struct X; | |
3124 | * struct X; | |
3125 | * struct X { | |
3126 | * int member; | |
3127 | * }; | |
3128 | * \endcode | |
3129 | * | |
3130 | * The declarations and the definition of \c X are represented by three | |
3131 | * different cursors, all of which are declarations of the same underlying | |
3132 | * entity. One of these cursor is considered the "canonical" cursor, which | |
3133 | * is effectively the representative for the underlying entity. One can | |
3134 | * determine if two cursors are declarations of the same underlying entity by | |
3135 | * comparing their canonical cursors. | |
3136 | * | |
3137 | * \returns The canonical cursor for the entity referred to by the given cursor. | |
3138 | */ | |
3139 | CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); | |
3140 | ||
3141 | ||
3142 | /** | |
3143 | * \brief If the cursor points to a selector identifier in a objc method or | |
3144 | * message expression, this returns the selector index. | |
3145 | * | |
3146 | * After getting a cursor with #clang_getCursor, this can be called to | |
3147 | * determine if the location points to a selector identifier. | |
3148 | * | |
3149 | * \returns The selector index if the cursor is an objc method or message | |
3150 | * expression and the cursor is pointing to a selector identifier, or -1 | |
3151 | * otherwise. | |
3152 | */ | |
3153 | CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor); | |
3154 | ||
3155 | /** | |
3156 | * \brief Given a cursor pointing to a C++ method call or an ObjC message, | |
3157 | * returns non-zero if the method/message is "dynamic", meaning: | |
3158 | * | |
3159 | * For a C++ method: the call is virtual. | |
3160 | * For an ObjC message: the receiver is an object instance, not 'super' or a | |
3161 | * specific class. | |
3162 | * | |
3163 | * If the method/message is "static" or the cursor does not point to a | |
3164 | * method/message, it will return zero. | |
3165 | */ | |
3166 | CINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C); | |
3167 | ||
3168 | /** | |
3169 | * \brief Given a cursor that represents a declaration, return the associated | |
3170 | * comment's source range. The range may include multiple consecutive comments | |
3171 | * with whitespace in between. | |
3172 | */ | |
3173 | CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange(CXCursor C); | |
3174 | ||
3175 | /** | |
3176 | * \brief Given a cursor that represents a declaration, return the associated | |
3177 | * comment text, including comment markers. | |
3178 | */ | |
3179 | CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C); | |
3180 | ||
3181 | /** | |
3182 | * \brief Given a cursor that represents a documentable entity (e.g., | |
3183 | * declaration), return the associated \\brief paragraph; otherwise return the | |
3184 | * first paragraph. | |
3185 | */ | |
3186 | CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C); | |
3187 | ||
3188 | /** | |
3189 | * \brief Given a cursor that represents a documentable entity (e.g., | |
3190 | * declaration), return the associated parsed comment as a | |
3191 | * \c CXComment_FullComment AST node. | |
3192 | */ | |
3193 | CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C); | |
3194 | ||
3195 | /** | |
3196 | * @} | |
3197 | */ | |
3198 | ||
3199 | /** | |
3200 | * \defgroup CINDEX_COMMENT Comment AST introspection | |
3201 | * | |
3202 | * The routines in this group provide access to information in the | |
3203 | * documentation comment ASTs. | |
3204 | * | |
3205 | * @{ | |
3206 | */ | |
3207 | ||
3208 | /** | |
3209 | * \brief Describes the type of the comment AST node (\c CXComment). A comment | |
3210 | * node can be considered block content (e. g., paragraph), inline content | |
3211 | * (plain text) or neither (the root AST node). | |
3212 | */ | |
3213 | enum CXCommentKind { | |
3214 | /** | |
3215 | * \brief Null comment. No AST node is constructed at the requested location | |
3216 | * because there is no text or a syntax error. | |
3217 | */ | |
3218 | CXComment_Null = 0, | |
3219 | ||
3220 | /** | |
3221 | * \brief Plain text. Inline content. | |
3222 | */ | |
3223 | CXComment_Text = 1, | |
3224 | ||
3225 | /** | |
3226 | * \brief A command with word-like arguments that is considered inline content. | |
3227 | * | |
3228 | * For example: \\c command. | |
3229 | */ | |
3230 | CXComment_InlineCommand = 2, | |
3231 | ||
3232 | /** | |
3233 | * \brief HTML start tag with attributes (name-value pairs). Considered | |
3234 | * inline content. | |
3235 | * | |
3236 | * For example: | |
3237 | * \verbatim | |
3238 | * <br> <br /> <a href="http://example.org/"> | |
3239 | * \endverbatim | |
3240 | */ | |
3241 | CXComment_HTMLStartTag = 3, | |
3242 | ||
3243 | /** | |
3244 | * \brief HTML end tag. Considered inline content. | |
3245 | * | |
3246 | * For example: | |
3247 | * \verbatim | |
3248 | * </a> | |
3249 | * \endverbatim | |
3250 | */ | |
3251 | CXComment_HTMLEndTag = 4, | |
3252 | ||
3253 | /** | |
3254 | * \brief A paragraph, contains inline comment. The paragraph itself is | |
3255 | * block content. | |
3256 | */ | |
3257 | CXComment_Paragraph = 5, | |
3258 | ||
3259 | /** | |
3260 | * \brief A command that has zero or more word-like arguments (number of | |
3261 | * word-like arguments depends on command name) and a paragraph as an | |
3262 | * argument. Block command is block content. | |
3263 | * | |
3264 | * Paragraph argument is also a child of the block command. | |
3265 | * | |
3266 | * For example: \\brief has 0 word-like arguments and a paragraph argument. | |
3267 | * | |
3268 | * AST nodes of special kinds that parser knows about (e. g., \\param | |
3269 | * command) have their own node kinds. | |
3270 | */ | |
3271 | CXComment_BlockCommand = 6, | |
3272 | ||
3273 | /** | |
3274 | * \brief A \\param or \\arg command that describes the function parameter | |
3275 | * (name, passing direction, description). | |
3276 | * | |
3277 | * For example: \\param [in] ParamName description. | |
3278 | */ | |
3279 | CXComment_ParamCommand = 7, | |
3280 | ||
3281 | /** | |
3282 | * \brief A \\tparam command that describes a template parameter (name and | |
3283 | * description). | |
3284 | * | |
3285 | * For example: \\tparam T description. | |
3286 | */ | |
3287 | CXComment_TParamCommand = 8, | |
3288 | ||
3289 | /** | |
3290 | * \brief A verbatim block command (e. g., preformatted code). Verbatim | |
3291 | * block has an opening and a closing command and contains multiple lines of | |
3292 | * text (\c CXComment_VerbatimBlockLine child nodes). | |
3293 | * | |
3294 | * For example: | |
3295 | * \\verbatim | |
3296 | * aaa | |
3297 | * \\endverbatim | |
3298 | */ | |
3299 | CXComment_VerbatimBlockCommand = 9, | |
3300 | ||
3301 | /** | |
3302 | * \brief A line of text that is contained within a | |
3303 | * CXComment_VerbatimBlockCommand node. | |
3304 | */ | |
3305 | CXComment_VerbatimBlockLine = 10, | |
3306 | ||
3307 | /** | |
3308 | * \brief A verbatim line command. Verbatim line has an opening command, | |
3309 | * a single line of text (up to the newline after the opening command) and | |
3310 | * has no closing command. | |
3311 | */ | |
3312 | CXComment_VerbatimLine = 11, | |
3313 | ||
3314 | /** | |
3315 | * \brief A full comment attached to a declaration, contains block content. | |
3316 | */ | |
3317 | CXComment_FullComment = 12 | |
3318 | }; | |
3319 | ||
3320 | /** | |
3321 | * \brief The most appropriate rendering mode for an inline command, chosen on | |
3322 | * command semantics in Doxygen. | |
3323 | */ | |
3324 | enum CXCommentInlineCommandRenderKind { | |
3325 | /** | |
3326 | * \brief Command argument should be rendered in a normal font. | |
3327 | */ | |
3328 | CXCommentInlineCommandRenderKind_Normal, | |
3329 | ||
3330 | /** | |
3331 | * \brief Command argument should be rendered in a bold font. | |
3332 | */ | |
3333 | CXCommentInlineCommandRenderKind_Bold, | |
3334 | ||
3335 | /** | |
3336 | * \brief Command argument should be rendered in a monospaced font. | |
3337 | */ | |
3338 | CXCommentInlineCommandRenderKind_Monospaced, | |
3339 | ||
3340 | /** | |
3341 | * \brief Command argument should be rendered emphasized (typically italic | |
3342 | * font). | |
3343 | */ | |
3344 | CXCommentInlineCommandRenderKind_Emphasized | |
3345 | }; | |
3346 | ||
3347 | /** | |
3348 | * \brief Describes parameter passing direction for \\param or \\arg command. | |
3349 | */ | |
3350 | enum CXCommentParamPassDirection { | |
3351 | /** | |
3352 | * \brief The parameter is an input parameter. | |
3353 | */ | |
3354 | CXCommentParamPassDirection_In, | |
3355 | ||
3356 | /** | |
3357 | * \brief The parameter is an output parameter. | |
3358 | */ | |
3359 | CXCommentParamPassDirection_Out, | |
3360 | ||
3361 | /** | |
3362 | * \brief The parameter is an input and output parameter. | |
3363 | */ | |
3364 | CXCommentParamPassDirection_InOut | |
3365 | }; | |
3366 | ||
3367 | /** | |
3368 | * \param Comment AST node of any kind. | |
3369 | * | |
3370 | * \returns the type of the AST node. | |
3371 | */ | |
3372 | CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment); | |
3373 | ||
3374 | /** | |
3375 | * \param Comment AST node of any kind. | |
3376 | * | |
3377 | * \returns number of children of the AST node. | |
3378 | */ | |
3379 | CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment); | |
3380 | ||
3381 | /** | |
3382 | * \param Comment AST node of any kind. | |
3383 | * | |
3384 | * \param ChildIdx child index (zero-based). | |
3385 | * | |
3386 | * \returns the specified child of the AST node. | |
3387 | */ | |
3388 | CINDEX_LINKAGE | |
3389 | CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx); | |
3390 | ||
3391 | /** | |
3392 | * \brief A \c CXComment_Paragraph node is considered whitespace if it contains | |
3393 | * only \c CXComment_Text nodes that are empty or whitespace. | |
3394 | * | |
3395 | * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are | |
3396 | * never considered whitespace. | |
3397 | * | |
3398 | * \returns non-zero if \c Comment is whitespace. | |
3399 | */ | |
3400 | CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment); | |
3401 | ||
3402 | /** | |
3403 | * \returns non-zero if \c Comment is inline content and has a newline | |
3404 | * immediately following it in the comment text. Newlines between paragraphs | |
3405 | * do not count. | |
3406 | */ | |
3407 | CINDEX_LINKAGE | |
3408 | unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment); | |
3409 | ||
3410 | /** | |
3411 | * \param Comment a \c CXComment_Text AST node. | |
3412 | * | |
3413 | * \returns text contained in the AST node. | |
3414 | */ | |
3415 | CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment); | |
3416 | ||
3417 | /** | |
3418 | * \param Comment a \c CXComment_InlineCommand AST node. | |
3419 | * | |
3420 | * \returns name of the inline command. | |
3421 | */ | |
3422 | CINDEX_LINKAGE | |
3423 | CXString clang_InlineCommandComment_getCommandName(CXComment Comment); | |
3424 | ||
3425 | /** | |
3426 | * \param Comment a \c CXComment_InlineCommand AST node. | |
3427 | * | |
3428 | * \returns the most appropriate rendering mode, chosen on command | |
3429 | * semantics in Doxygen. | |
3430 | */ | |
3431 | CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind | |
3432 | clang_InlineCommandComment_getRenderKind(CXComment Comment); | |
3433 | ||
3434 | /** | |
3435 | * \param Comment a \c CXComment_InlineCommand AST node. | |
3436 | * | |
3437 | * \returns number of command arguments. | |
3438 | */ | |
3439 | CINDEX_LINKAGE | |
3440 | unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment); | |
3441 | ||
3442 | /** | |
3443 | * \param Comment a \c CXComment_InlineCommand AST node. | |
3444 | * | |
3445 | * \param ArgIdx argument index (zero-based). | |
3446 | * | |
3447 | * \returns text of the specified argument. | |
3448 | */ | |
3449 | CINDEX_LINKAGE | |
3450 | CXString clang_InlineCommandComment_getArgText(CXComment Comment, | |
3451 | unsigned ArgIdx); | |
3452 | ||
3453 | /** | |
3454 | * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST | |
3455 | * node. | |
3456 | * | |
3457 | * \returns HTML tag name. | |
3458 | */ | |
3459 | CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment); | |
3460 | ||
3461 | /** | |
3462 | * \param Comment a \c CXComment_HTMLStartTag AST node. | |
3463 | * | |
3464 | * \returns non-zero if tag is self-closing (for example, <br />). | |
3465 | */ | |
3466 | CINDEX_LINKAGE | |
3467 | unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment); | |
3468 | ||
3469 | /** | |
3470 | * \param Comment a \c CXComment_HTMLStartTag AST node. | |
3471 | * | |
3472 | * \returns number of attributes (name-value pairs) attached to the start tag. | |
3473 | */ | |
3474 | CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment); | |
3475 | ||
3476 | /** | |
3477 | * \param Comment a \c CXComment_HTMLStartTag AST node. | |
3478 | * | |
3479 | * \param AttrIdx attribute index (zero-based). | |
3480 | * | |
3481 | * \returns name of the specified attribute. | |
3482 | */ | |
3483 | CINDEX_LINKAGE | |
3484 | CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx); | |
3485 | ||
3486 | /** | |
3487 | * \param Comment a \c CXComment_HTMLStartTag AST node. | |
3488 | * | |
3489 | * \param AttrIdx attribute index (zero-based). | |
3490 | * | |
3491 | * \returns value of the specified attribute. | |
3492 | */ | |
3493 | CINDEX_LINKAGE | |
3494 | CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx); | |
3495 | ||
3496 | /** | |
3497 | * \param Comment a \c CXComment_BlockCommand AST node. | |
3498 | * | |
3499 | * \returns name of the block command. | |
3500 | */ | |
3501 | CINDEX_LINKAGE | |
3502 | CXString clang_BlockCommandComment_getCommandName(CXComment Comment); | |
3503 | ||
3504 | /** | |
3505 | * \param Comment a \c CXComment_BlockCommand AST node. | |
3506 | * | |
3507 | * \returns number of word-like arguments. | |
3508 | */ | |
3509 | CINDEX_LINKAGE | |
3510 | unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment); | |
3511 | ||
3512 | /** | |
3513 | * \param Comment a \c CXComment_BlockCommand AST node. | |
3514 | * | |
3515 | * \param ArgIdx argument index (zero-based). | |
3516 | * | |
3517 | * \returns text of the specified word-like argument. | |
3518 | */ | |
3519 | CINDEX_LINKAGE | |
3520 | CXString clang_BlockCommandComment_getArgText(CXComment Comment, | |
3521 | unsigned ArgIdx); | |
3522 | ||
3523 | /** | |
3524 | * \param Comment a \c CXComment_BlockCommand or | |
3525 | * \c CXComment_VerbatimBlockCommand AST node. | |
3526 | * | |
3527 | * \returns paragraph argument of the block command. | |
3528 | */ | |
3529 | CINDEX_LINKAGE | |
3530 | CXComment clang_BlockCommandComment_getParagraph(CXComment Comment); | |
3531 | ||
3532 | /** | |
3533 | * \param Comment a \c CXComment_ParamCommand AST node. | |
3534 | * | |
3535 | * \returns parameter name. | |
3536 | */ | |
3537 | CINDEX_LINKAGE | |
3538 | CXString clang_ParamCommandComment_getParamName(CXComment Comment); | |
3539 | ||
3540 | /** | |
3541 | * \param Comment a \c CXComment_ParamCommand AST node. | |
3542 | * | |
3543 | * \returns non-zero if the parameter that this AST node represents was found | |
3544 | * in the function prototype and \c clang_ParamCommandComment_getParamIndex | |
3545 | * function will return a meaningful value. | |
3546 | */ | |
3547 | CINDEX_LINKAGE | |
3548 | unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment); | |
3549 | ||
3550 | /** | |
3551 | * \param Comment a \c CXComment_ParamCommand AST node. | |
3552 | * | |
3553 | * \returns zero-based parameter index in function prototype. | |
3554 | */ | |
3555 | CINDEX_LINKAGE | |
3556 | unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment); | |
3557 | ||
3558 | /** | |
3559 | * \param Comment a \c CXComment_ParamCommand AST node. | |
3560 | * | |
3561 | * \returns non-zero if parameter passing direction was specified explicitly in | |
3562 | * the comment. | |
3563 | */ | |
3564 | CINDEX_LINKAGE | |
3565 | unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment); | |
3566 | ||
3567 | /** | |
3568 | * \param Comment a \c CXComment_ParamCommand AST node. | |
3569 | * | |
3570 | * \returns parameter passing direction. | |
3571 | */ | |
3572 | CINDEX_LINKAGE | |
3573 | enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection( | |
3574 | CXComment Comment); | |
3575 | ||
3576 | /** | |
3577 | * \param Comment a \c CXComment_TParamCommand AST node. | |
3578 | * | |
3579 | * \returns template parameter name. | |
3580 | */ | |
3581 | CINDEX_LINKAGE | |
3582 | CXString clang_TParamCommandComment_getParamName(CXComment Comment); | |
3583 | ||
3584 | /** | |
3585 | * \param Comment a \c CXComment_TParamCommand AST node. | |
3586 | * | |
3587 | * \returns non-zero if the parameter that this AST node represents was found | |
3588 | * in the template parameter list and | |
3589 | * \c clang_TParamCommandComment_getDepth and | |
3590 | * \c clang_TParamCommandComment_getIndex functions will return a meaningful | |
3591 | * value. | |
3592 | */ | |
3593 | CINDEX_LINKAGE | |
3594 | unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment); | |
3595 | ||
3596 | /** | |
3597 | * \param Comment a \c CXComment_TParamCommand AST node. | |
3598 | * | |
3599 | * \returns zero-based nesting depth of this parameter in the template parameter list. | |
3600 | * | |
3601 | * For example, | |
3602 | * \verbatim | |
3603 | * template<typename C, template<typename T> class TT> | |
3604 | * void test(TT<int> aaa); | |
3605 | * \endverbatim | |
3606 | * for C and TT nesting depth is 0, | |
3607 | * for T nesting depth is 1. | |
3608 | */ | |
3609 | CINDEX_LINKAGE | |
3610 | unsigned clang_TParamCommandComment_getDepth(CXComment Comment); | |
3611 | ||
3612 | /** | |
3613 | * \param Comment a \c CXComment_TParamCommand AST node. | |
3614 | * | |
3615 | * \returns zero-based parameter index in the template parameter list at a | |
3616 | * given nesting depth. | |
3617 | * | |
3618 | * For example, | |
3619 | * \verbatim | |
3620 | * template<typename C, template<typename T> class TT> | |
3621 | * void test(TT<int> aaa); | |
3622 | * \endverbatim | |
3623 | * for C and TT nesting depth is 0, so we can ask for index at depth 0: | |
3624 | * at depth 0 C's index is 0, TT's index is 1. | |
3625 | * | |
3626 | * For T nesting depth is 1, so we can ask for index at depth 0 and 1: | |
3627 | * at depth 0 T's index is 1 (same as TT's), | |
3628 | * at depth 1 T's index is 0. | |
3629 | */ | |
3630 | CINDEX_LINKAGE | |
3631 | unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth); | |
3632 | ||
3633 | /** | |
3634 | * \param Comment a \c CXComment_VerbatimBlockLine AST node. | |
3635 | * | |
3636 | * \returns text contained in the AST node. | |
3637 | */ | |
3638 | CINDEX_LINKAGE | |
3639 | CXString clang_VerbatimBlockLineComment_getText(CXComment Comment); | |
3640 | ||
3641 | /** | |
3642 | * \param Comment a \c CXComment_VerbatimLine AST node. | |
3643 | * | |
3644 | * \returns text contained in the AST node. | |
3645 | */ | |
3646 | CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment); | |
3647 | ||
3648 | /** | |
3649 | * \brief Convert an HTML tag AST node to string. | |
3650 | * | |
3651 | * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST | |
3652 | * node. | |
3653 | * | |
3654 | * \returns string containing an HTML tag. | |
3655 | */ | |
3656 | CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment); | |
3657 | ||
3658 | /** | |
3659 | * \brief Convert a given full parsed comment to an HTML fragment. | |
3660 | * | |
3661 | * Specific details of HTML layout are subject to change. Don't try to parse | |
3662 | * this HTML back into an AST, use other APIs instead. | |
3663 | * | |
3664 | * Currently the following CSS classes are used: | |
3665 | * \li "para-brief" for \\brief paragraph and equivalent commands; | |
3666 | * \li "para-returns" for \\returns paragraph and equivalent commands; | |
3667 | * \li "word-returns" for the "Returns" word in \\returns paragraph. | |
3668 | * | |
3669 | * Function argument documentation is rendered as a \<dl\> list with arguments | |
3670 | * sorted in function prototype order. CSS classes used: | |
3671 | * \li "param-name-index-NUMBER" for parameter name (\<dt\>); | |
3672 | * \li "param-descr-index-NUMBER" for parameter description (\<dd\>); | |
3673 | * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if | |
3674 | * parameter index is invalid. | |
3675 | * | |
3676 | * Template parameter documentation is rendered as a \<dl\> list with | |
3677 | * parameters sorted in template parameter list order. CSS classes used: | |
3678 | * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>); | |
3679 | * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>); | |
3680 | * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for | |
3681 | * names inside template template parameters; | |
3682 | * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if | |
3683 | * parameter position is invalid. | |
3684 | * | |
3685 | * \param Comment a \c CXComment_FullComment AST node. | |
3686 | * | |
3687 | * \returns string containing an HTML fragment. | |
3688 | */ | |
3689 | CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment); | |
3690 | ||
3691 | /** | |
3692 | * \brief Convert a given full parsed comment to an XML document. | |
3693 | * | |
3694 | * A Relax NG schema for the XML can be found in comment-xml-schema.rng file | |
3695 | * inside clang source tree. | |
3696 | * | |
3697 | * \param Comment a \c CXComment_FullComment AST node. | |
3698 | * | |
3699 | * \returns string containing an XML document. | |
3700 | */ | |
3701 | CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment); | |
3702 | ||
3703 | /** | |
3704 | * @} | |
3705 | */ | |
3706 | ||
3707 | /** | |
3708 | * \defgroup CINDEX_CPP C++ AST introspection | |
3709 | * | |
3710 | * The routines in this group provide access information in the ASTs specific | |
3711 | * to C++ language features. | |
3712 | * | |
3713 | * @{ | |
3714 | */ | |
3715 | ||
3716 | /** | |
3717 | * \brief Determine if a C++ member function or member function template is | |
3718 | * declared 'static'. | |
3719 | */ | |
3720 | CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); | |
3721 | ||
3722 | /** | |
3723 | * \brief Determine if a C++ member function or member function template is | |
3724 | * explicitly declared 'virtual' or if it overrides a virtual method from | |
3725 | * one of the base classes. | |
3726 | */ | |
3727 | CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C); | |
3728 | ||
3729 | /** | |
3730 | * \brief Given a cursor that represents a template, determine | |
3731 | * the cursor kind of the specializations would be generated by instantiating | |
3732 | * the template. | |
3733 | * | |
3734 | * This routine can be used to determine what flavor of function template, | |
3735 | * class template, or class template partial specialization is stored in the | |
3736 | * cursor. For example, it can describe whether a class template cursor is | |
3737 | * declared with "struct", "class" or "union". | |
3738 | * | |
3739 | * \param C The cursor to query. This cursor should represent a template | |
3740 | * declaration. | |
3741 | * | |
3742 | * \returns The cursor kind of the specializations that would be generated | |
3743 | * by instantiating the template \p C. If \p C is not a template, returns | |
3744 | * \c CXCursor_NoDeclFound. | |
3745 | */ | |
3746 | CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); | |
3747 | ||
3748 | /** | |
3749 | * \brief Given a cursor that may represent a specialization or instantiation | |
3750 | * of a template, retrieve the cursor that represents the template that it | |
3751 | * specializes or from which it was instantiated. | |
3752 | * | |
3753 | * This routine determines the template involved both for explicit | |
3754 | * specializations of templates and for implicit instantiations of the template, | |
3755 | * both of which are referred to as "specializations". For a class template | |
3756 | * specialization (e.g., \c std::vector<bool>), this routine will return | |
3757 | * either the primary template (\c std::vector) or, if the specialization was | |
3758 | * instantiated from a class template partial specialization, the class template | |
3759 | * partial specialization. For a class template partial specialization and a | |
3760 | * function template specialization (including instantiations), this | |
3761 | * this routine will return the specialized template. | |
3762 | * | |
3763 | * For members of a class template (e.g., member functions, member classes, or | |
3764 | * static data members), returns the specialized or instantiated member. | |
3765 | * Although not strictly "templates" in the C++ language, members of class | |
3766 | * templates have the same notions of specializations and instantiations that | |
3767 | * templates do, so this routine treats them similarly. | |
3768 | * | |
3769 | * \param C A cursor that may be a specialization of a template or a member | |
3770 | * of a template. | |
3771 | * | |
3772 | * \returns If the given cursor is a specialization or instantiation of a | |
3773 | * template or a member thereof, the template or member that it specializes or | |
3774 | * from which it was instantiated. Otherwise, returns a NULL cursor. | |
3775 | */ | |
3776 | CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C); | |
3777 | ||
3778 | /** | |
3779 | * \brief Given a cursor that references something else, return the source range | |
3780 | * covering that reference. | |
3781 | * | |
3782 | * \param C A cursor pointing to a member reference, a declaration reference, or | |
3783 | * an operator call. | |
3784 | * \param NameFlags A bitset with three independent flags: | |
3785 | * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and | |
3786 | * CXNameRange_WantSinglePiece. | |
3787 | * \param PieceIndex For contiguous names or when passing the flag | |
3788 | * CXNameRange_WantSinglePiece, only one piece with index 0 is | |
3789 | * available. When the CXNameRange_WantSinglePiece flag is not passed for a | |
3790 | * non-contiguous names, this index can be used to retrieve the individual | |
3791 | * pieces of the name. See also CXNameRange_WantSinglePiece. | |
3792 | * | |
3793 | * \returns The piece of the name pointed to by the given cursor. If there is no | |
3794 | * name, or if the PieceIndex is out-of-range, a null-cursor will be returned. | |
3795 | */ | |
3796 | CINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(CXCursor C, | |
3797 | unsigned NameFlags, | |
3798 | unsigned PieceIndex); | |
3799 | ||
3800 | enum CXNameRefFlags { | |
3801 | /** | |
3802 | * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the | |
3803 | * range. | |
3804 | */ | |
3805 | CXNameRange_WantQualifier = 0x1, | |
3806 | ||
3807 | /** | |
3808 | * \brief Include the explicit template arguments, e.g. \<int> in x.f<int>, | |
3809 | * in the range. | |
3810 | */ | |
3811 | CXNameRange_WantTemplateArgs = 0x2, | |
3812 | ||
3813 | /** | |
3814 | * \brief If the name is non-contiguous, return the full spanning range. | |
3815 | * | |
3816 | * Non-contiguous names occur in Objective-C when a selector with two or more | |
3817 | * parameters is used, or in C++ when using an operator: | |
3818 | * \code | |
3819 | * [object doSomething:here withValue:there]; // ObjC | |
3820 | * return some_vector[1]; // C++ | |
3821 | * \endcode | |
3822 | */ | |
3823 | CXNameRange_WantSinglePiece = 0x4 | |
3824 | }; | |
3825 | ||
3826 | /** | |
3827 | * @} | |
3828 | */ | |
3829 | ||
3830 | /** | |
3831 | * \defgroup CINDEX_LEX Token extraction and manipulation | |
3832 | * | |
3833 | * The routines in this group provide access to the tokens within a | |
3834 | * translation unit, along with a semantic mapping of those tokens to | |
3835 | * their corresponding cursors. | |
3836 | * | |
3837 | * @{ | |
3838 | */ | |
3839 | ||
3840 | /** | |
3841 | * \brief Describes a kind of token. | |
3842 | */ | |
3843 | typedef enum CXTokenKind { | |
3844 | /** | |
3845 | * \brief A token that contains some kind of punctuation. | |
3846 | */ | |
3847 | CXToken_Punctuation, | |
3848 | ||
3849 | /** | |
3850 | * \brief A language keyword. | |
3851 | */ | |
3852 | CXToken_Keyword, | |
3853 | ||
3854 | /** | |
3855 | * \brief An identifier (that is not a keyword). | |
3856 | */ | |
3857 | CXToken_Identifier, | |
3858 | ||
3859 | /** | |
3860 | * \brief A numeric, string, or character literal. | |
3861 | */ | |
3862 | CXToken_Literal, | |
3863 | ||
3864 | /** | |
3865 | * \brief A comment. | |
3866 | */ | |
3867 | CXToken_Comment | |
3868 | } CXTokenKind; | |
3869 | ||
3870 | /** | |
3871 | * \brief Describes a single preprocessing token. | |
3872 | */ | |
3873 | typedef struct { | |
3874 | unsigned int_data[4]; | |
3875 | void *ptr_data; | |
3876 | } CXToken; | |
3877 | ||
3878 | /** | |
3879 | * \brief Determine the kind of the given token. | |
3880 | */ | |
3881 | CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); | |
3882 | ||
3883 | /** | |
3884 | * \brief Determine the spelling of the given token. | |
3885 | * | |
3886 | * The spelling of a token is the textual representation of that token, e.g., | |
3887 | * the text of an identifier or keyword. | |
3888 | */ | |
3889 | CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); | |
3890 | ||
3891 | /** | |
3892 | * \brief Retrieve the source location of the given token. | |
3893 | */ | |
3894 | CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, | |
3895 | CXToken); | |
3896 | ||
3897 | /** | |
3898 | * \brief Retrieve a source range that covers the given token. | |
3899 | */ | |
3900 | CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); | |
3901 | ||
3902 | /** | |
3903 | * \brief Tokenize the source code described by the given range into raw | |
3904 | * lexical tokens. | |
3905 | * | |
3906 | * \param TU the translation unit whose text is being tokenized. | |
3907 | * | |
3908 | * \param Range the source range in which text should be tokenized. All of the | |
3909 | * tokens produced by tokenization will fall within this source range, | |
3910 | * | |
3911 | * \param Tokens this pointer will be set to point to the array of tokens | |
3912 | * that occur within the given source range. The returned pointer must be | |
3913 | * freed with clang_disposeTokens() before the translation unit is destroyed. | |
3914 | * | |
3915 | * \param NumTokens will be set to the number of tokens in the \c *Tokens | |
3916 | * array. | |
3917 | * | |
3918 | */ | |
3919 | CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, | |
3920 | CXToken **Tokens, unsigned *NumTokens); | |
3921 | ||
3922 | /** | |
3923 | * \brief Annotate the given set of tokens by providing cursors for each token | |
3924 | * that can be mapped to a specific entity within the abstract syntax tree. | |
3925 | * | |
3926 | * This token-annotation routine is equivalent to invoking | |
3927 | * clang_getCursor() for the source locations of each of the | |
3928 | * tokens. The cursors provided are filtered, so that only those | |
3929 | * cursors that have a direct correspondence to the token are | |
3930 | * accepted. For example, given a function call \c f(x), | |
3931 | * clang_getCursor() would provide the following cursors: | |
3932 | * | |
3933 | * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. | |
3934 | * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. | |
3935 | * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. | |
3936 | * | |
3937 | * Only the first and last of these cursors will occur within the | |
3938 | * annotate, since the tokens "f" and "x' directly refer to a function | |
3939 | * and a variable, respectively, but the parentheses are just a small | |
3940 | * part of the full syntax of the function call expression, which is | |
3941 | * not provided as an annotation. | |
3942 | * | |
3943 | * \param TU the translation unit that owns the given tokens. | |
3944 | * | |
3945 | * \param Tokens the set of tokens to annotate. | |
3946 | * | |
3947 | * \param NumTokens the number of tokens in \p Tokens. | |
3948 | * | |
3949 | * \param Cursors an array of \p NumTokens cursors, whose contents will be | |
3950 | * replaced with the cursors corresponding to each token. | |
3951 | */ | |
3952 | CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, | |
3953 | CXToken *Tokens, unsigned NumTokens, | |
3954 | CXCursor *Cursors); | |
3955 | ||
3956 | /** | |
3957 | * \brief Free the given set of tokens. | |
3958 | */ | |
3959 | CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, | |
3960 | CXToken *Tokens, unsigned NumTokens); | |
3961 | ||
3962 | /** | |
3963 | * @} | |
3964 | */ | |
3965 | ||
3966 | /** | |
3967 | * \defgroup CINDEX_DEBUG Debugging facilities | |
3968 | * | |
3969 | * These routines are used for testing and debugging, only, and should not | |
3970 | * be relied upon. | |
3971 | * | |
3972 | * @{ | |
3973 | */ | |
3974 | ||
3975 | /* for debug/testing */ | |
3976 | CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); | |
3977 | CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, | |
3978 | const char **startBuf, | |
3979 | const char **endBuf, | |
3980 | unsigned *startLine, | |
3981 | unsigned *startColumn, | |
3982 | unsigned *endLine, | |
3983 | unsigned *endColumn); | |
3984 | CINDEX_LINKAGE void clang_enableStackTraces(void); | |
3985 | CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, | |
3986 | unsigned stack_size); | |
3987 | ||
3988 | /** | |
3989 | * @} | |
3990 | */ | |
3991 | ||
3992 | /** | |
3993 | * \defgroup CINDEX_CODE_COMPLET Code completion | |
3994 | * | |
3995 | * Code completion involves taking an (incomplete) source file, along with | |
3996 | * knowledge of where the user is actively editing that file, and suggesting | |
3997 | * syntactically- and semantically-valid constructs that the user might want to | |
3998 | * use at that particular point in the source code. These data structures and | |
3999 | * routines provide support for code completion. | |
4000 | * | |
4001 | * @{ | |
4002 | */ | |
4003 | ||
4004 | /** | |
4005 | * \brief A semantic string that describes a code-completion result. | |
4006 | * | |
4007 | * A semantic string that describes the formatting of a code-completion | |
4008 | * result as a single "template" of text that should be inserted into the | |
4009 | * source buffer when a particular code-completion result is selected. | |
4010 | * Each semantic string is made up of some number of "chunks", each of which | |
4011 | * contains some text along with a description of what that text means, e.g., | |
4012 | * the name of the entity being referenced, whether the text chunk is part of | |
4013 | * the template, or whether it is a "placeholder" that the user should replace | |
4014 | * with actual code,of a specific kind. See \c CXCompletionChunkKind for a | |
4015 | * description of the different kinds of chunks. | |
4016 | */ | |
4017 | typedef void *CXCompletionString; | |
4018 | ||
4019 | /** | |
4020 | * \brief A single result of code completion. | |
4021 | */ | |
4022 | typedef struct { | |
4023 | /** | |
4024 | * \brief The kind of entity that this completion refers to. | |
4025 | * | |
4026 | * The cursor kind will be a macro, keyword, or a declaration (one of the | |
4027 | * *Decl cursor kinds), describing the entity that the completion is | |
4028 | * referring to. | |
4029 | * | |
4030 | * \todo In the future, we would like to provide a full cursor, to allow | |
4031 | * the client to extract additional information from declaration. | |
4032 | */ | |
4033 | enum CXCursorKind CursorKind; | |
4034 | ||
4035 | /** | |
4036 | * \brief The code-completion string that describes how to insert this | |
4037 | * code-completion result into the editing buffer. | |
4038 | */ | |
4039 | CXCompletionString CompletionString; | |
4040 | } CXCompletionResult; | |
4041 | ||
4042 | /** | |
4043 | * \brief Describes a single piece of text within a code-completion string. | |
4044 | * | |
4045 | * Each "chunk" within a code-completion string (\c CXCompletionString) is | |
4046 | * either a piece of text with a specific "kind" that describes how that text | |
4047 | * should be interpreted by the client or is another completion string. | |
4048 | */ | |
4049 | enum CXCompletionChunkKind { | |
4050 | /** | |
4051 | * \brief A code-completion string that describes "optional" text that | |
4052 | * could be a part of the template (but is not required). | |
4053 | * | |
4054 | * The Optional chunk is the only kind of chunk that has a code-completion | |
4055 | * string for its representation, which is accessible via | |
4056 | * \c clang_getCompletionChunkCompletionString(). The code-completion string | |
4057 | * describes an additional part of the template that is completely optional. | |
4058 | * For example, optional chunks can be used to describe the placeholders for | |
4059 | * arguments that match up with defaulted function parameters, e.g. given: | |
4060 | * | |
4061 | * \code | |
4062 | * void f(int x, float y = 3.14, double z = 2.71828); | |
4063 | * \endcode | |
4064 | * | |
4065 | * The code-completion string for this function would contain: | |
4066 | * - a TypedText chunk for "f". | |
4067 | * - a LeftParen chunk for "(". | |
4068 | * - a Placeholder chunk for "int x" | |
4069 | * - an Optional chunk containing the remaining defaulted arguments, e.g., | |
4070 | * - a Comma chunk for "," | |
4071 | * - a Placeholder chunk for "float y" | |
4072 | * - an Optional chunk containing the last defaulted argument: | |
4073 | * - a Comma chunk for "," | |
4074 | * - a Placeholder chunk for "double z" | |
4075 | * - a RightParen chunk for ")" | |
4076 | * | |
4077 | * There are many ways to handle Optional chunks. Two simple approaches are: | |
4078 | * - Completely ignore optional chunks, in which case the template for the | |
4079 | * function "f" would only include the first parameter ("int x"). | |
4080 | * - Fully expand all optional chunks, in which case the template for the | |
4081 | * function "f" would have all of the parameters. | |
4082 | */ | |
4083 | CXCompletionChunk_Optional, | |
4084 | /** | |
4085 | * \brief Text that a user would be expected to type to get this | |
4086 | * code-completion result. | |
4087 | * | |
4088 | * There will be exactly one "typed text" chunk in a semantic string, which | |
4089 | * will typically provide the spelling of a keyword or the name of a | |
4090 | * declaration that could be used at the current code point. Clients are | |
4091 | * expected to filter the code-completion results based on the text in this | |
4092 | * chunk. | |
4093 | */ | |
4094 | CXCompletionChunk_TypedText, | |
4095 | /** | |
4096 | * \brief Text that should be inserted as part of a code-completion result. | |
4097 | * | |
4098 | * A "text" chunk represents text that is part of the template to be | |
4099 | * inserted into user code should this particular code-completion result | |
4100 | * be selected. | |
4101 | */ | |
4102 | CXCompletionChunk_Text, | |
4103 | /** | |
4104 | * \brief Placeholder text that should be replaced by the user. | |
4105 | * | |
4106 | * A "placeholder" chunk marks a place where the user should insert text | |
4107 | * into the code-completion template. For example, placeholders might mark | |
4108 | * the function parameters for a function declaration, to indicate that the | |
4109 | * user should provide arguments for each of those parameters. The actual | |
4110 | * text in a placeholder is a suggestion for the text to display before | |
4111 | * the user replaces the placeholder with real code. | |
4112 | */ | |
4113 | CXCompletionChunk_Placeholder, | |
4114 | /** | |
4115 | * \brief Informative text that should be displayed but never inserted as | |
4116 | * part of the template. | |
4117 | * | |
4118 | * An "informative" chunk contains annotations that can be displayed to | |
4119 | * help the user decide whether a particular code-completion result is the | |
4120 | * right option, but which is not part of the actual template to be inserted | |
4121 | * by code completion. | |
4122 | */ | |
4123 | CXCompletionChunk_Informative, | |
4124 | /** | |
4125 | * \brief Text that describes the current parameter when code-completion is | |
4126 | * referring to function call, message send, or template specialization. | |
4127 | * | |
4128 | * A "current parameter" chunk occurs when code-completion is providing | |
4129 | * information about a parameter corresponding to the argument at the | |
4130 | * code-completion point. For example, given a function | |
4131 | * | |
4132 | * \code | |
4133 | * int add(int x, int y); | |
4134 | * \endcode | |
4135 | * | |
4136 | * and the source code \c add(, where the code-completion point is after the | |
4137 | * "(", the code-completion string will contain a "current parameter" chunk | |
4138 | * for "int x", indicating that the current argument will initialize that | |
4139 | * parameter. After typing further, to \c add(17, (where the code-completion | |
4140 | * point is after the ","), the code-completion string will contain a | |
4141 | * "current paremeter" chunk to "int y". | |
4142 | */ | |
4143 | CXCompletionChunk_CurrentParameter, | |
4144 | /** | |
4145 | * \brief A left parenthesis ('('), used to initiate a function call or | |
4146 | * signal the beginning of a function parameter list. | |
4147 | */ | |
4148 | CXCompletionChunk_LeftParen, | |
4149 | /** | |
4150 | * \brief A right parenthesis (')'), used to finish a function call or | |
4151 | * signal the end of a function parameter list. | |
4152 | */ | |
4153 | CXCompletionChunk_RightParen, | |
4154 | /** | |
4155 | * \brief A left bracket ('['). | |
4156 | */ | |
4157 | CXCompletionChunk_LeftBracket, | |
4158 | /** | |
4159 | * \brief A right bracket (']'). | |
4160 | */ | |
4161 | CXCompletionChunk_RightBracket, | |
4162 | /** | |
4163 | * \brief A left brace ('{'). | |
4164 | */ | |
4165 | CXCompletionChunk_LeftBrace, | |
4166 | /** | |
4167 | * \brief A right brace ('}'). | |
4168 | */ | |
4169 | CXCompletionChunk_RightBrace, | |
4170 | /** | |
4171 | * \brief A left angle bracket ('<'). | |
4172 | */ | |
4173 | CXCompletionChunk_LeftAngle, | |
4174 | /** | |
4175 | * \brief A right angle bracket ('>'). | |
4176 | */ | |
4177 | CXCompletionChunk_RightAngle, | |
4178 | /** | |
4179 | * \brief A comma separator (','). | |
4180 | */ | |
4181 | CXCompletionChunk_Comma, | |
4182 | /** | |
4183 | * \brief Text that specifies the result type of a given result. | |
4184 | * | |
4185 | * This special kind of informative chunk is not meant to be inserted into | |
4186 | * the text buffer. Rather, it is meant to illustrate the type that an | |
4187 | * expression using the given completion string would have. | |
4188 | */ | |
4189 | CXCompletionChunk_ResultType, | |
4190 | /** | |
4191 | * \brief A colon (':'). | |
4192 | */ | |
4193 | CXCompletionChunk_Colon, | |
4194 | /** | |
4195 | * \brief A semicolon (';'). | |
4196 | */ | |
4197 | CXCompletionChunk_SemiColon, | |
4198 | /** | |
4199 | * \brief An '=' sign. | |
4200 | */ | |
4201 | CXCompletionChunk_Equal, | |
4202 | /** | |
4203 | * Horizontal space (' '). | |
4204 | */ | |
4205 | CXCompletionChunk_HorizontalSpace, | |
4206 | /** | |
4207 | * Vertical space ('\n'), after which it is generally a good idea to | |
4208 | * perform indentation. | |
4209 | */ | |
4210 | CXCompletionChunk_VerticalSpace | |
4211 | }; | |
4212 | ||
4213 | /** | |
4214 | * \brief Determine the kind of a particular chunk within a completion string. | |
4215 | * | |
4216 | * \param completion_string the completion string to query. | |
4217 | * | |
4218 | * \param chunk_number the 0-based index of the chunk in the completion string. | |
4219 | * | |
4220 | * \returns the kind of the chunk at the index \c chunk_number. | |
4221 | */ | |
4222 | CINDEX_LINKAGE enum CXCompletionChunkKind | |
4223 | clang_getCompletionChunkKind(CXCompletionString completion_string, | |
4224 | unsigned chunk_number); | |
4225 | ||
4226 | /** | |
4227 | * \brief Retrieve the text associated with a particular chunk within a | |
4228 | * completion string. | |
4229 | * | |
4230 | * \param completion_string the completion string to query. | |
4231 | * | |
4232 | * \param chunk_number the 0-based index of the chunk in the completion string. | |
4233 | * | |
4234 | * \returns the text associated with the chunk at index \c chunk_number. | |
4235 | */ | |
4236 | CINDEX_LINKAGE CXString | |
4237 | clang_getCompletionChunkText(CXCompletionString completion_string, | |
4238 | unsigned chunk_number); | |
4239 | ||
4240 | /** | |
4241 | * \brief Retrieve the completion string associated with a particular chunk | |
4242 | * within a completion string. | |
4243 | * | |
4244 | * \param completion_string the completion string to query. | |
4245 | * | |
4246 | * \param chunk_number the 0-based index of the chunk in the completion string. | |
4247 | * | |
4248 | * \returns the completion string associated with the chunk at index | |
4249 | * \c chunk_number. | |
4250 | */ | |
4251 | CINDEX_LINKAGE CXCompletionString | |
4252 | clang_getCompletionChunkCompletionString(CXCompletionString completion_string, | |
4253 | unsigned chunk_number); | |
4254 | ||
4255 | /** | |
4256 | * \brief Retrieve the number of chunks in the given code-completion string. | |
4257 | */ | |
4258 | CINDEX_LINKAGE unsigned | |
4259 | clang_getNumCompletionChunks(CXCompletionString completion_string); | |
4260 | ||
4261 | /** | |
4262 | * \brief Determine the priority of this code completion. | |
4263 | * | |
4264 | * The priority of a code completion indicates how likely it is that this | |
4265 | * particular completion is the completion that the user will select. The | |
4266 | * priority is selected by various internal heuristics. | |
4267 | * | |
4268 | * \param completion_string The completion string to query. | |
4269 | * | |
4270 | * \returns The priority of this completion string. Smaller values indicate | |
4271 | * higher-priority (more likely) completions. | |
4272 | */ | |
4273 | CINDEX_LINKAGE unsigned | |
4274 | clang_getCompletionPriority(CXCompletionString completion_string); | |
4275 | ||
4276 | /** | |
4277 | * \brief Determine the availability of the entity that this code-completion | |
4278 | * string refers to. | |
4279 | * | |
4280 | * \param completion_string The completion string to query. | |
4281 | * | |
4282 | * \returns The availability of the completion string. | |
4283 | */ | |
4284 | CINDEX_LINKAGE enum CXAvailabilityKind | |
4285 | clang_getCompletionAvailability(CXCompletionString completion_string); | |
4286 | ||
4287 | /** | |
4288 | * \brief Retrieve the number of annotations associated with the given | |
4289 | * completion string. | |
4290 | * | |
4291 | * \param completion_string the completion string to query. | |
4292 | * | |
4293 | * \returns the number of annotations associated with the given completion | |
4294 | * string. | |
4295 | */ | |
4296 | CINDEX_LINKAGE unsigned | |
4297 | clang_getCompletionNumAnnotations(CXCompletionString completion_string); | |
4298 | ||
4299 | /** | |
4300 | * \brief Retrieve the annotation associated with the given completion string. | |
4301 | * | |
4302 | * \param completion_string the completion string to query. | |
4303 | * | |
4304 | * \param annotation_number the 0-based index of the annotation of the | |
4305 | * completion string. | |
4306 | * | |
4307 | * \returns annotation string associated with the completion at index | |
4308 | * \c annotation_number, or a NULL string if that annotation is not available. | |
4309 | */ | |
4310 | CINDEX_LINKAGE CXString | |
4311 | clang_getCompletionAnnotation(CXCompletionString completion_string, | |
4312 | unsigned annotation_number); | |
4313 | ||
4314 | /** | |
4315 | * \brief Retrieve the parent context of the given completion string. | |
4316 | * | |
4317 | * The parent context of a completion string is the semantic parent of | |
4318 | * the declaration (if any) that the code completion represents. For example, | |
4319 | * a code completion for an Objective-C method would have the method's class | |
4320 | * or protocol as its context. | |
4321 | * | |
4322 | * \param completion_string The code completion string whose parent is | |
4323 | * being queried. | |
4324 | * | |
4325 | * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL. | |
4326 | * | |
4327 | * \returns The name of the completion parent, e.g., "NSObject" if | |
4328 | * the completion string represents a method in the NSObject class. | |
4329 | */ | |
4330 | CINDEX_LINKAGE CXString | |
4331 | clang_getCompletionParent(CXCompletionString completion_string, | |
4332 | enum CXCursorKind *kind); | |
4333 | ||
4334 | /** | |
4335 | * \brief Retrieve the brief documentation comment attached to the declaration | |
4336 | * that corresponds to the given completion string. | |
4337 | */ | |
4338 | CINDEX_LINKAGE CXString | |
4339 | clang_getCompletionBriefComment(CXCompletionString completion_string); | |
4340 | ||
4341 | /** | |
4342 | * \brief Retrieve a completion string for an arbitrary declaration or macro | |
4343 | * definition cursor. | |
4344 | * | |
4345 | * \param cursor The cursor to query. | |
4346 | * | |
4347 | * \returns A non-context-sensitive completion string for declaration and macro | |
4348 | * definition cursors, or NULL for other kinds of cursors. | |
4349 | */ | |
4350 | CINDEX_LINKAGE CXCompletionString | |
4351 | clang_getCursorCompletionString(CXCursor cursor); | |
4352 | ||
4353 | /** | |
4354 | * \brief Contains the results of code-completion. | |
4355 | * | |
4356 | * This data structure contains the results of code completion, as | |
4357 | * produced by \c clang_codeCompleteAt(). Its contents must be freed by | |
4358 | * \c clang_disposeCodeCompleteResults. | |
4359 | */ | |
4360 | typedef struct { | |
4361 | /** | |
4362 | * \brief The code-completion results. | |
4363 | */ | |
4364 | CXCompletionResult *Results; | |
4365 | ||
4366 | /** | |
4367 | * \brief The number of code-completion results stored in the | |
4368 | * \c Results array. | |
4369 | */ | |
4370 | unsigned NumResults; | |
4371 | } CXCodeCompleteResults; | |
4372 | ||
4373 | /** | |
4374 | * \brief Flags that can be passed to \c clang_codeCompleteAt() to | |
4375 | * modify its behavior. | |
4376 | * | |
4377 | * The enumerators in this enumeration can be bitwise-OR'd together to | |
4378 | * provide multiple options to \c clang_codeCompleteAt(). | |
4379 | */ | |
4380 | enum CXCodeComplete_Flags { | |
4381 | /** | |
4382 | * \brief Whether to include macros within the set of code | |
4383 | * completions returned. | |
4384 | */ | |
4385 | CXCodeComplete_IncludeMacros = 0x01, | |
4386 | ||
4387 | /** | |
4388 | * \brief Whether to include code patterns for language constructs | |
4389 | * within the set of code completions, e.g., for loops. | |
4390 | */ | |
4391 | CXCodeComplete_IncludeCodePatterns = 0x02, | |
4392 | ||
4393 | /** | |
4394 | * \brief Whether to include brief documentation within the set of code | |
4395 | * completions returned. | |
4396 | */ | |
4397 | CXCodeComplete_IncludeBriefComments = 0x04 | |
4398 | }; | |
4399 | ||
4400 | /** | |
4401 | * \brief Bits that represent the context under which completion is occurring. | |
4402 | * | |
4403 | * The enumerators in this enumeration may be bitwise-OR'd together if multiple | |
4404 | * contexts are occurring simultaneously. | |
4405 | */ | |
4406 | enum CXCompletionContext { | |
4407 | /** | |
4408 | * \brief The context for completions is unexposed, as only Clang results | |
4409 | * should be included. (This is equivalent to having no context bits set.) | |
4410 | */ | |
4411 | CXCompletionContext_Unexposed = 0, | |
4412 | ||
4413 | /** | |
4414 | * \brief Completions for any possible type should be included in the results. | |
4415 | */ | |
4416 | CXCompletionContext_AnyType = 1 << 0, | |
4417 | ||
4418 | /** | |
4419 | * \brief Completions for any possible value (variables, function calls, etc.) | |
4420 | * should be included in the results. | |
4421 | */ | |
4422 | CXCompletionContext_AnyValue = 1 << 1, | |
4423 | /** | |
4424 | * \brief Completions for values that resolve to an Objective-C object should | |
4425 | * be included in the results. | |
4426 | */ | |
4427 | CXCompletionContext_ObjCObjectValue = 1 << 2, | |
4428 | /** | |
4429 | * \brief Completions for values that resolve to an Objective-C selector | |
4430 | * should be included in the results. | |
4431 | */ | |
4432 | CXCompletionContext_ObjCSelectorValue = 1 << 3, | |
4433 | /** | |
4434 | * \brief Completions for values that resolve to a C++ class type should be | |
4435 | * included in the results. | |
4436 | */ | |
4437 | CXCompletionContext_CXXClassTypeValue = 1 << 4, | |
4438 | ||
4439 | /** | |
4440 | * \brief Completions for fields of the member being accessed using the dot | |
4441 | * operator should be included in the results. | |
4442 | */ | |
4443 | CXCompletionContext_DotMemberAccess = 1 << 5, | |
4444 | /** | |
4445 | * \brief Completions for fields of the member being accessed using the arrow | |
4446 | * operator should be included in the results. | |
4447 | */ | |
4448 | CXCompletionContext_ArrowMemberAccess = 1 << 6, | |
4449 | /** | |
4450 | * \brief Completions for properties of the Objective-C object being accessed | |
4451 | * using the dot operator should be included in the results. | |
4452 | */ | |
4453 | CXCompletionContext_ObjCPropertyAccess = 1 << 7, | |
4454 | ||
4455 | /** | |
4456 | * \brief Completions for enum tags should be included in the results. | |
4457 | */ | |
4458 | CXCompletionContext_EnumTag = 1 << 8, | |
4459 | /** | |
4460 | * \brief Completions for union tags should be included in the results. | |
4461 | */ | |
4462 | CXCompletionContext_UnionTag = 1 << 9, | |
4463 | /** | |
4464 | * \brief Completions for struct tags should be included in the results. | |
4465 | */ | |
4466 | CXCompletionContext_StructTag = 1 << 10, | |
4467 | ||
4468 | /** | |
4469 | * \brief Completions for C++ class names should be included in the results. | |
4470 | */ | |
4471 | CXCompletionContext_ClassTag = 1 << 11, | |
4472 | /** | |
4473 | * \brief Completions for C++ namespaces and namespace aliases should be | |
4474 | * included in the results. | |
4475 | */ | |
4476 | CXCompletionContext_Namespace = 1 << 12, | |
4477 | /** | |
4478 | * \brief Completions for C++ nested name specifiers should be included in | |
4479 | * the results. | |
4480 | */ | |
4481 | CXCompletionContext_NestedNameSpecifier = 1 << 13, | |
4482 | ||
4483 | /** | |
4484 | * \brief Completions for Objective-C interfaces (classes) should be included | |
4485 | * in the results. | |
4486 | */ | |
4487 | CXCompletionContext_ObjCInterface = 1 << 14, | |
4488 | /** | |
4489 | * \brief Completions for Objective-C protocols should be included in | |
4490 | * the results. | |
4491 | */ | |
4492 | CXCompletionContext_ObjCProtocol = 1 << 15, | |
4493 | /** | |
4494 | * \brief Completions for Objective-C categories should be included in | |
4495 | * the results. | |
4496 | */ | |
4497 | CXCompletionContext_ObjCCategory = 1 << 16, | |
4498 | /** | |
4499 | * \brief Completions for Objective-C instance messages should be included | |
4500 | * in the results. | |
4501 | */ | |
4502 | CXCompletionContext_ObjCInstanceMessage = 1 << 17, | |
4503 | /** | |
4504 | * \brief Completions for Objective-C class messages should be included in | |
4505 | * the results. | |
4506 | */ | |
4507 | CXCompletionContext_ObjCClassMessage = 1 << 18, | |
4508 | /** | |
4509 | * \brief Completions for Objective-C selector names should be included in | |
4510 | * the results. | |
4511 | */ | |
4512 | CXCompletionContext_ObjCSelectorName = 1 << 19, | |
4513 | ||
4514 | /** | |
4515 | * \brief Completions for preprocessor macro names should be included in | |
4516 | * the results. | |
4517 | */ | |
4518 | CXCompletionContext_MacroName = 1 << 20, | |
4519 | ||
4520 | /** | |
4521 | * \brief Natural language completions should be included in the results. | |
4522 | */ | |
4523 | CXCompletionContext_NaturalLanguage = 1 << 21, | |
4524 | ||
4525 | /** | |
4526 | * \brief The current context is unknown, so set all contexts. | |
4527 | */ | |
4528 | CXCompletionContext_Unknown = ((1 << 22) - 1) | |
4529 | }; | |
4530 | ||
4531 | /** | |
4532 | * \brief Returns a default set of code-completion options that can be | |
4533 | * passed to\c clang_codeCompleteAt(). | |
4534 | */ | |
4535 | CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); | |
4536 | ||
4537 | /** | |
4538 | * \brief Perform code completion at a given location in a translation unit. | |
4539 | * | |
4540 | * This function performs code completion at a particular file, line, and | |
4541 | * column within source code, providing results that suggest potential | |
4542 | * code snippets based on the context of the completion. The basic model | |
4543 | * for code completion is that Clang will parse a complete source file, | |
4544 | * performing syntax checking up to the location where code-completion has | |
4545 | * been requested. At that point, a special code-completion token is passed | |
4546 | * to the parser, which recognizes this token and determines, based on the | |
4547 | * current location in the C/Objective-C/C++ grammar and the state of | |
4548 | * semantic analysis, what completions to provide. These completions are | |
4549 | * returned via a new \c CXCodeCompleteResults structure. | |
4550 | * | |
4551 | * Code completion itself is meant to be triggered by the client when the | |
4552 | * user types punctuation characters or whitespace, at which point the | |
4553 | * code-completion location will coincide with the cursor. For example, if \c p | |
4554 | * is a pointer, code-completion might be triggered after the "-" and then | |
4555 | * after the ">" in \c p->. When the code-completion location is afer the ">", | |
4556 | * the completion results will provide, e.g., the members of the struct that | |
4557 | * "p" points to. The client is responsible for placing the cursor at the | |
4558 | * beginning of the token currently being typed, then filtering the results | |
4559 | * based on the contents of the token. For example, when code-completing for | |
4560 | * the expression \c p->get, the client should provide the location just after | |
4561 | * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the | |
4562 | * client can filter the results based on the current token text ("get"), only | |
4563 | * showing those results that start with "get". The intent of this interface | |
4564 | * is to separate the relatively high-latency acquisition of code-completion | |
4565 | * results from the filtering of results on a per-character basis, which must | |
4566 | * have a lower latency. | |
4567 | * | |
4568 | * \param TU The translation unit in which code-completion should | |
4569 | * occur. The source files for this translation unit need not be | |
4570 | * completely up-to-date (and the contents of those source files may | |
4571 | * be overridden via \p unsaved_files). Cursors referring into the | |
4572 | * translation unit may be invalidated by this invocation. | |
4573 | * | |
4574 | * \param complete_filename The name of the source file where code | |
4575 | * completion should be performed. This filename may be any file | |
4576 | * included in the translation unit. | |
4577 | * | |
4578 | * \param complete_line The line at which code-completion should occur. | |
4579 | * | |
4580 | * \param complete_column The column at which code-completion should occur. | |
4581 | * Note that the column should point just after the syntactic construct that | |
4582 | * initiated code completion, and not in the middle of a lexical token. | |
4583 | * | |
4584 | * \param unsaved_files the Tiles that have not yet been saved to disk | |
4585 | * but may be required for parsing or code completion, including the | |
4586 | * contents of those files. The contents and name of these files (as | |
4587 | * specified by CXUnsavedFile) are copied when necessary, so the | |
4588 | * client only needs to guarantee their validity until the call to | |
4589 | * this function returns. | |
4590 | * | |
4591 | * \param num_unsaved_files The number of unsaved file entries in \p | |
4592 | * unsaved_files. | |
4593 | * | |
4594 | * \param options Extra options that control the behavior of code | |
4595 | * completion, expressed as a bitwise OR of the enumerators of the | |
4596 | * CXCodeComplete_Flags enumeration. The | |
4597 | * \c clang_defaultCodeCompleteOptions() function returns a default set | |
4598 | * of code-completion options. | |
4599 | * | |
4600 | * \returns If successful, a new \c CXCodeCompleteResults structure | |
4601 | * containing code-completion results, which should eventually be | |
4602 | * freed with \c clang_disposeCodeCompleteResults(). If code | |
4603 | * completion fails, returns NULL. | |
4604 | */ | |
4605 | CINDEX_LINKAGE | |
4606 | CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU, | |
4607 | const char *complete_filename, | |
4608 | unsigned complete_line, | |
4609 | unsigned complete_column, | |
4610 | struct CXUnsavedFile *unsaved_files, | |
4611 | unsigned num_unsaved_files, | |
4612 | unsigned options); | |
4613 | ||
4614 | /** | |
4615 | * \brief Sort the code-completion results in case-insensitive alphabetical | |
4616 | * order. | |
4617 | * | |
4618 | * \param Results The set of results to sort. | |
4619 | * \param NumResults The number of results in \p Results. | |
4620 | */ | |
4621 | CINDEX_LINKAGE | |
4622 | void clang_sortCodeCompletionResults(CXCompletionResult *Results, | |
4623 | unsigned NumResults); | |
4624 | ||
4625 | /** | |
4626 | * \brief Free the given set of code-completion results. | |
4627 | */ | |
4628 | CINDEX_LINKAGE | |
4629 | void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); | |
4630 | ||
4631 | /** | |
4632 | * \brief Determine the number of diagnostics produced prior to the | |
4633 | * location where code completion was performed. | |
4634 | */ | |
4635 | CINDEX_LINKAGE | |
4636 | unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); | |
4637 | ||
4638 | /** | |
4639 | * \brief Retrieve a diagnostic associated with the given code completion. | |
4640 | * | |
4641 | * \param Results the code completion results to query. | |
4642 | * \param Index the zero-based diagnostic number to retrieve. | |
4643 | * | |
4644 | * \returns the requested diagnostic. This diagnostic must be freed | |
4645 | * via a call to \c clang_disposeDiagnostic(). | |
4646 | */ | |
4647 | CINDEX_LINKAGE | |
4648 | CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, | |
4649 | unsigned Index); | |
4650 | ||
4651 | /** | |
4652 | * \brief Determines what compeltions are appropriate for the context | |
4653 | * the given code completion. | |
4654 | * | |
4655 | * \param Results the code completion results to query | |
4656 | * | |
4657 | * \returns the kinds of completions that are appropriate for use | |
4658 | * along with the given code completion results. | |
4659 | */ | |
4660 | CINDEX_LINKAGE | |
4661 | unsigned long long clang_codeCompleteGetContexts( | |
4662 | CXCodeCompleteResults *Results); | |
4663 | ||
4664 | /** | |
4665 | * \brief Returns the cursor kind for the container for the current code | |
4666 | * completion context. The container is only guaranteed to be set for | |
4667 | * contexts where a container exists (i.e. member accesses or Objective-C | |
4668 | * message sends); if there is not a container, this function will return | |
4669 | * CXCursor_InvalidCode. | |
4670 | * | |
4671 | * \param Results the code completion results to query | |
4672 | * | |
4673 | * \param IsIncomplete on return, this value will be false if Clang has complete | |
4674 | * information about the container. If Clang does not have complete | |
4675 | * information, this value will be true. | |
4676 | * | |
4677 | * \returns the container kind, or CXCursor_InvalidCode if there is not a | |
4678 | * container | |
4679 | */ | |
4680 | CINDEX_LINKAGE | |
4681 | enum CXCursorKind clang_codeCompleteGetContainerKind( | |
4682 | CXCodeCompleteResults *Results, | |
4683 | unsigned *IsIncomplete); | |
4684 | ||
4685 | /** | |
4686 | * \brief Returns the USR for the container for the current code completion | |
4687 | * context. If there is not a container for the current context, this | |
4688 | * function will return the empty string. | |
4689 | * | |
4690 | * \param Results the code completion results to query | |
4691 | * | |
4692 | * \returns the USR for the container | |
4693 | */ | |
4694 | CINDEX_LINKAGE | |
4695 | CXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results); | |
4696 | ||
4697 | ||
4698 | /** | |
4699 | * \brief Returns the currently-entered selector for an Objective-C message | |
4700 | * send, formatted like "initWithFoo:bar:". Only guaranteed to return a | |
4701 | * non-empty string for CXCompletionContext_ObjCInstanceMessage and | |
4702 | * CXCompletionContext_ObjCClassMessage. | |
4703 | * | |
4704 | * \param Results the code completion results to query | |
4705 | * | |
4706 | * \returns the selector (or partial selector) that has been entered thus far | |
4707 | * for an Objective-C message send. | |
4708 | */ | |
4709 | CINDEX_LINKAGE | |
4710 | CXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results); | |
4711 | ||
4712 | /** | |
4713 | * @} | |
4714 | */ | |
4715 | ||
4716 | ||
4717 | /** | |
4718 | * \defgroup CINDEX_MISC Miscellaneous utility functions | |
4719 | * | |
4720 | * @{ | |
4721 | */ | |
4722 | ||
4723 | /** | |
4724 | * \brief Return a version string, suitable for showing to a user, but not | |
4725 | * intended to be parsed (the format is not guaranteed to be stable). | |
4726 | */ | |
4727 | CINDEX_LINKAGE CXString clang_getClangVersion(); | |
4728 | ||
4729 | ||
4730 | /** | |
4731 | * \brief Enable/disable crash recovery. | |
4732 | * | |
4733 | * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero | |
4734 | * value enables crash recovery, while 0 disables it. | |
4735 | */ | |
4736 | CINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled); | |
4737 | ||
4738 | /** | |
4739 | * \brief Visitor invoked for each file in a translation unit | |
4740 | * (used with clang_getInclusions()). | |
4741 | * | |
4742 | * This visitor function will be invoked by clang_getInclusions() for each | |
4743 | * file included (either at the top-level or by \#include directives) within | |
4744 | * a translation unit. The first argument is the file being included, and | |
4745 | * the second and third arguments provide the inclusion stack. The | |
4746 | * array is sorted in order of immediate inclusion. For example, | |
4747 | * the first element refers to the location that included 'included_file'. | |
4748 | */ | |
4749 | typedef void (*CXInclusionVisitor)(CXFile included_file, | |
4750 | CXSourceLocation* inclusion_stack, | |
4751 | unsigned include_len, | |
4752 | CXClientData client_data); | |
4753 | ||
4754 | /** | |
4755 | * \brief Visit the set of preprocessor inclusions in a translation unit. | |
4756 | * The visitor function is called with the provided data for every included | |
4757 | * file. This does not include headers included by the PCH file (unless one | |
4758 | * is inspecting the inclusions in the PCH file itself). | |
4759 | */ | |
4760 | CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, | |
4761 | CXInclusionVisitor visitor, | |
4762 | CXClientData client_data); | |
4763 | ||
4764 | /** | |
4765 | * @} | |
4766 | */ | |
4767 | ||
4768 | /** \defgroup CINDEX_REMAPPING Remapping functions | |
4769 | * | |
4770 | * @{ | |
4771 | */ | |
4772 | ||
4773 | /** | |
4774 | * \brief A remapping of original source files and their translated files. | |
4775 | */ | |
4776 | typedef void *CXRemapping; | |
4777 | ||
4778 | /** | |
4779 | * \brief Retrieve a remapping. | |
4780 | * | |
4781 | * \param path the path that contains metadata about remappings. | |
4782 | * | |
4783 | * \returns the requested remapping. This remapping must be freed | |
4784 | * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. | |
4785 | */ | |
4786 | CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path); | |
4787 | ||
4788 | /** | |
4789 | * \brief Retrieve a remapping. | |
4790 | * | |
4791 | * \param filePaths pointer to an array of file paths containing remapping info. | |
4792 | * | |
4793 | * \param numFiles number of file paths. | |
4794 | * | |
4795 | * \returns the requested remapping. This remapping must be freed | |
4796 | * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. | |
4797 | */ | |
4798 | CINDEX_LINKAGE | |
4799 | CXRemapping clang_getRemappingsFromFileList(const char **filePaths, | |
4800 | unsigned numFiles); | |
4801 | ||
4802 | /** | |
4803 | * \brief Determine the number of remappings. | |
4804 | */ | |
4805 | CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping); | |
4806 | ||
4807 | /** | |
4808 | * \brief Get the original and the associated filename from the remapping. | |
4809 | * | |
4810 | * \param original If non-NULL, will be set to the original filename. | |
4811 | * | |
4812 | * \param transformed If non-NULL, will be set to the filename that the original | |
4813 | * is associated with. | |
4814 | */ | |
4815 | CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index, | |
4816 | CXString *original, CXString *transformed); | |
4817 | ||
4818 | /** | |
4819 | * \brief Dispose the remapping. | |
4820 | */ | |
4821 | CINDEX_LINKAGE void clang_remap_dispose(CXRemapping); | |
4822 | ||
4823 | /** | |
4824 | * @} | |
4825 | */ | |
4826 | ||
4827 | /** \defgroup CINDEX_HIGH Higher level API functions | |
4828 | * | |
4829 | * @{ | |
4830 | */ | |
4831 | ||
4832 | enum CXVisitorResult { | |
4833 | CXVisit_Break, | |
4834 | CXVisit_Continue | |
4835 | }; | |
4836 | ||
4837 | typedef struct { | |
4838 | void *context; | |
4839 | enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange); | |
4840 | } CXCursorAndRangeVisitor; | |
4841 | ||
4842 | /** | |
4843 | * \brief Find references of a declaration in a specific file. | |
4844 | * | |
4845 | * \param cursor pointing to a declaration or a reference of one. | |
4846 | * | |
4847 | * \param file to search for references. | |
4848 | * | |
4849 | * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for | |
4850 | * each reference found. | |
4851 | * The CXSourceRange will point inside the file; if the reference is inside | |
4852 | * a macro (and not a macro argument) the CXSourceRange will be invalid. | |
4853 | */ | |
4854 | CINDEX_LINKAGE void clang_findReferencesInFile(CXCursor cursor, CXFile file, | |
4855 | CXCursorAndRangeVisitor visitor); | |
4856 | ||
4857 | #ifdef __has_feature | |
4858 | # if __has_feature(blocks) | |
4859 | ||
4860 | typedef enum CXVisitorResult | |
4861 | (^CXCursorAndRangeVisitorBlock)(CXCursor, CXSourceRange); | |
4862 | ||
4863 | CINDEX_LINKAGE | |
4864 | void clang_findReferencesInFileWithBlock(CXCursor, CXFile, | |
4865 | CXCursorAndRangeVisitorBlock); | |
4866 | ||
4867 | # endif | |
4868 | #endif | |
4869 | ||
4870 | /** | |
4871 | * \brief The client's data object that is associated with a CXFile. | |
4872 | */ | |
4873 | typedef void *CXIdxClientFile; | |
4874 | ||
4875 | /** | |
4876 | * \brief The client's data object that is associated with a semantic entity. | |
4877 | */ | |
4878 | typedef void *CXIdxClientEntity; | |
4879 | ||
4880 | /** | |
4881 | * \brief The client's data object that is associated with a semantic container | |
4882 | * of entities. | |
4883 | */ | |
4884 | typedef void *CXIdxClientContainer; | |
4885 | ||
4886 | /** | |
4887 | * \brief The client's data object that is associated with an AST file (PCH | |
4888 | * or module). | |
4889 | */ | |
4890 | typedef void *CXIdxClientASTFile; | |
4891 | ||
4892 | /** | |
4893 | * \brief Source location passed to index callbacks. | |
4894 | */ | |
4895 | typedef struct { | |
4896 | void *ptr_data[2]; | |
4897 | unsigned int_data; | |
4898 | } CXIdxLoc; | |
4899 | ||
4900 | /** | |
4901 | * \brief Data for ppIncludedFile callback. | |
4902 | */ | |
4903 | typedef struct { | |
4904 | /** | |
4905 | * \brief Location of '#' in the \#include/\#import directive. | |
4906 | */ | |
4907 | CXIdxLoc hashLoc; | |
4908 | /** | |
4909 | * \brief Filename as written in the \#include/\#import directive. | |
4910 | */ | |
4911 | const char *filename; | |
4912 | /** | |
4913 | * \brief The actual file that the \#include/\#import directive resolved to. | |
4914 | */ | |
4915 | CXFile file; | |
4916 | int isImport; | |
4917 | int isAngled; | |
4918 | } CXIdxIncludedFileInfo; | |
4919 | ||
4920 | /** | |
4921 | * \brief Data for IndexerCallbacks#importedASTFile. | |
4922 | */ | |
4923 | typedef struct { | |
4924 | CXFile file; | |
4925 | /** | |
4926 | * \brief Location where the file is imported. It is useful mostly for | |
4927 | * modules. | |
4928 | */ | |
4929 | CXIdxLoc loc; | |
4930 | /** | |
4931 | * \brief Non-zero if the AST file is a module otherwise it's a PCH. | |
4932 | */ | |
4933 | int isModule; | |
4934 | } CXIdxImportedASTFileInfo; | |
4935 | ||
4936 | typedef enum { | |
4937 | CXIdxEntity_Unexposed = 0, | |
4938 | CXIdxEntity_Typedef = 1, | |
4939 | CXIdxEntity_Function = 2, | |
4940 | CXIdxEntity_Variable = 3, | |
4941 | CXIdxEntity_Field = 4, | |
4942 | CXIdxEntity_EnumConstant = 5, | |
4943 | ||
4944 | CXIdxEntity_ObjCClass = 6, | |
4945 | CXIdxEntity_ObjCProtocol = 7, | |
4946 | CXIdxEntity_ObjCCategory = 8, | |
4947 | ||
4948 | CXIdxEntity_ObjCInstanceMethod = 9, | |
4949 | CXIdxEntity_ObjCClassMethod = 10, | |
4950 | CXIdxEntity_ObjCProperty = 11, | |
4951 | CXIdxEntity_ObjCIvar = 12, | |
4952 | ||
4953 | CXIdxEntity_Enum = 13, | |
4954 | CXIdxEntity_Struct = 14, | |
4955 | CXIdxEntity_Union = 15, | |
4956 | ||
4957 | CXIdxEntity_CXXClass = 16, | |
4958 | CXIdxEntity_CXXNamespace = 17, | |
4959 | CXIdxEntity_CXXNamespaceAlias = 18, | |
4960 | CXIdxEntity_CXXStaticVariable = 19, | |
4961 | CXIdxEntity_CXXStaticMethod = 20, | |
4962 | CXIdxEntity_CXXInstanceMethod = 21, | |
4963 | CXIdxEntity_CXXConstructor = 22, | |
4964 | CXIdxEntity_CXXDestructor = 23, | |
4965 | CXIdxEntity_CXXConversionFunction = 24, | |
4966 | CXIdxEntity_CXXTypeAlias = 25, | |
4967 | CXIdxEntity_CXXInterface = 26 | |
4968 | ||
4969 | } CXIdxEntityKind; | |
4970 | ||
4971 | typedef enum { | |
4972 | CXIdxEntityLang_None = 0, | |
4973 | CXIdxEntityLang_C = 1, | |
4974 | CXIdxEntityLang_ObjC = 2, | |
4975 | CXIdxEntityLang_CXX = 3 | |
4976 | } CXIdxEntityLanguage; | |
4977 | ||
4978 | /** | |
4979 | * \brief Extra C++ template information for an entity. This can apply to: | |
4980 | * CXIdxEntity_Function | |
4981 | * CXIdxEntity_CXXClass | |
4982 | * CXIdxEntity_CXXStaticMethod | |
4983 | * CXIdxEntity_CXXInstanceMethod | |
4984 | * CXIdxEntity_CXXConstructor | |
4985 | * CXIdxEntity_CXXConversionFunction | |
4986 | * CXIdxEntity_CXXTypeAlias | |
4987 | */ | |
4988 | typedef enum { | |
4989 | CXIdxEntity_NonTemplate = 0, | |
4990 | CXIdxEntity_Template = 1, | |
4991 | CXIdxEntity_TemplatePartialSpecialization = 2, | |
4992 | CXIdxEntity_TemplateSpecialization = 3 | |
4993 | } CXIdxEntityCXXTemplateKind; | |
4994 | ||
4995 | typedef enum { | |
4996 | CXIdxAttr_Unexposed = 0, | |
4997 | CXIdxAttr_IBAction = 1, | |
4998 | CXIdxAttr_IBOutlet = 2, | |
4999 | CXIdxAttr_IBOutletCollection = 3 | |
5000 | } CXIdxAttrKind; | |
5001 | ||
5002 | typedef struct { | |
5003 | CXIdxAttrKind kind; | |
5004 | CXCursor cursor; | |
5005 | CXIdxLoc loc; | |
5006 | } CXIdxAttrInfo; | |
5007 | ||
5008 | typedef struct { | |
5009 | CXIdxEntityKind kind; | |
5010 | CXIdxEntityCXXTemplateKind templateKind; | |
5011 | CXIdxEntityLanguage lang; | |
5012 | const char *name; | |
5013 | const char *USR; | |
5014 | CXCursor cursor; | |
5015 | const CXIdxAttrInfo *const *attributes; | |
5016 | unsigned numAttributes; | |
5017 | } CXIdxEntityInfo; | |
5018 | ||
5019 | typedef struct { | |
5020 | CXCursor cursor; | |
5021 | } CXIdxContainerInfo; | |
5022 | ||
5023 | typedef struct { | |
5024 | const CXIdxAttrInfo *attrInfo; | |
5025 | const CXIdxEntityInfo *objcClass; | |
5026 | CXCursor classCursor; | |
5027 | CXIdxLoc classLoc; | |
5028 | } CXIdxIBOutletCollectionAttrInfo; | |
5029 | ||
5030 | typedef struct { | |
5031 | const CXIdxEntityInfo *entityInfo; | |
5032 | CXCursor cursor; | |
5033 | CXIdxLoc loc; | |
5034 | const CXIdxContainerInfo *semanticContainer; | |
5035 | /** | |
5036 | * \brief Generally same as #semanticContainer but can be different in | |
5037 | * cases like out-of-line C++ member functions. | |
5038 | */ | |
5039 | const CXIdxContainerInfo *lexicalContainer; | |
5040 | int isRedeclaration; | |
5041 | int isDefinition; | |
5042 | int isContainer; | |
5043 | const CXIdxContainerInfo *declAsContainer; | |
5044 | /** | |
5045 | * \brief Whether the declaration exists in code or was created implicitly | |
5046 | * by the compiler, e.g. implicit objc methods for properties. | |
5047 | */ | |
5048 | int isImplicit; | |
5049 | const CXIdxAttrInfo *const *attributes; | |
5050 | unsigned numAttributes; | |
5051 | } CXIdxDeclInfo; | |
5052 | ||
5053 | typedef enum { | |
5054 | CXIdxObjCContainer_ForwardRef = 0, | |
5055 | CXIdxObjCContainer_Interface = 1, | |
5056 | CXIdxObjCContainer_Implementation = 2 | |
5057 | } CXIdxObjCContainerKind; | |
5058 | ||
5059 | typedef struct { | |
5060 | const CXIdxDeclInfo *declInfo; | |
5061 | CXIdxObjCContainerKind kind; | |
5062 | } CXIdxObjCContainerDeclInfo; | |
5063 | ||
5064 | typedef struct { | |
5065 | const CXIdxEntityInfo *base; | |
5066 | CXCursor cursor; | |
5067 | CXIdxLoc loc; | |
5068 | } CXIdxBaseClassInfo; | |
5069 | ||
5070 | typedef struct { | |
5071 | const CXIdxEntityInfo *protocol; | |
5072 | CXCursor cursor; | |
5073 | CXIdxLoc loc; | |
5074 | } CXIdxObjCProtocolRefInfo; | |
5075 | ||
5076 | typedef struct { | |
5077 | const CXIdxObjCProtocolRefInfo *const *protocols; | |
5078 | unsigned numProtocols; | |
5079 | } CXIdxObjCProtocolRefListInfo; | |
5080 | ||
5081 | typedef struct { | |
5082 | const CXIdxObjCContainerDeclInfo *containerInfo; | |
5083 | const CXIdxBaseClassInfo *superInfo; | |
5084 | const CXIdxObjCProtocolRefListInfo *protocols; | |
5085 | } CXIdxObjCInterfaceDeclInfo; | |
5086 | ||
5087 | typedef struct { | |
5088 | const CXIdxObjCContainerDeclInfo *containerInfo; | |
5089 | const CXIdxEntityInfo *objcClass; | |
5090 | CXCursor classCursor; | |
5091 | CXIdxLoc classLoc; | |
5092 | const CXIdxObjCProtocolRefListInfo *protocols; | |
5093 | } CXIdxObjCCategoryDeclInfo; | |
5094 | ||
5095 | typedef struct { | |
5096 | const CXIdxDeclInfo *declInfo; | |
5097 | const CXIdxEntityInfo *getter; | |
5098 | const CXIdxEntityInfo *setter; | |
5099 | } CXIdxObjCPropertyDeclInfo; | |
5100 | ||
5101 | typedef struct { | |
5102 | const CXIdxDeclInfo *declInfo; | |
5103 | const CXIdxBaseClassInfo *const *bases; | |
5104 | unsigned numBases; | |
5105 | } CXIdxCXXClassDeclInfo; | |
5106 | ||
5107 | /** | |
5108 | * \brief Data for IndexerCallbacks#indexEntityReference. | |
5109 | */ | |
5110 | typedef enum { | |
5111 | /** | |
5112 | * \brief The entity is referenced directly in user's code. | |
5113 | */ | |
5114 | CXIdxEntityRef_Direct = 1, | |
5115 | /** | |
5116 | * \brief An implicit reference, e.g. a reference of an ObjC method via the | |
5117 | * dot syntax. | |
5118 | */ | |
5119 | CXIdxEntityRef_Implicit = 2 | |
5120 | } CXIdxEntityRefKind; | |
5121 | ||
5122 | /** | |
5123 | * \brief Data for IndexerCallbacks#indexEntityReference. | |
5124 | */ | |
5125 | typedef struct { | |
5126 | CXIdxEntityRefKind kind; | |
5127 | /** | |
5128 | * \brief Reference cursor. | |
5129 | */ | |
5130 | CXCursor cursor; | |
5131 | CXIdxLoc loc; | |
5132 | /** | |
5133 | * \brief The entity that gets referenced. | |
5134 | */ | |
5135 | const CXIdxEntityInfo *referencedEntity; | |
5136 | /** | |
5137 | * \brief Immediate "parent" of the reference. For example: | |
5138 | * | |
5139 | * \code | |
5140 | * Foo *var; | |
5141 | * \endcode | |
5142 | * | |
5143 | * The parent of reference of type 'Foo' is the variable 'var'. | |
5144 | * For references inside statement bodies of functions/methods, | |
5145 | * the parentEntity will be the function/method. | |
5146 | */ | |
5147 | const CXIdxEntityInfo *parentEntity; | |
5148 | /** | |
5149 | * \brief Lexical container context of the reference. | |
5150 | */ | |
5151 | const CXIdxContainerInfo *container; | |
5152 | } CXIdxEntityRefInfo; | |
5153 | ||
5154 | /** | |
5155 | * \brief A group of callbacks used by #clang_indexSourceFile and | |
5156 | * #clang_indexTranslationUnit. | |
5157 | */ | |
5158 | typedef struct { | |
5159 | /** | |
5160 | * \brief Called periodically to check whether indexing should be aborted. | |
5161 | * Should return 0 to continue, and non-zero to abort. | |
5162 | */ | |
5163 | int (*abortQuery)(CXClientData client_data, void *reserved); | |
5164 | ||
5165 | /** | |
5166 | * \brief Called at the end of indexing; passes the complete diagnostic set. | |
5167 | */ | |
5168 | void (*diagnostic)(CXClientData client_data, | |
5169 | CXDiagnosticSet, void *reserved); | |
5170 | ||
5171 | CXIdxClientFile (*enteredMainFile)(CXClientData client_data, | |
5172 | CXFile mainFile, void *reserved); | |
5173 | ||
5174 | /** | |
5175 | * \brief Called when a file gets \#included/\#imported. | |
5176 | */ | |
5177 | CXIdxClientFile (*ppIncludedFile)(CXClientData client_data, | |
5178 | const CXIdxIncludedFileInfo *); | |
5179 | ||
5180 | /** | |
5181 | * \brief Called when a AST file (PCH or module) gets imported. | |
5182 | * | |
5183 | * AST files will not get indexed (there will not be callbacks to index all | |
5184 | * the entities in an AST file). The recommended action is that, if the AST | |
5185 | * file is not already indexed, to block further indexing and initiate a new | |
5186 | * indexing job specific to the AST file. | |
5187 | */ | |
5188 | CXIdxClientASTFile (*importedASTFile)(CXClientData client_data, | |
5189 | const CXIdxImportedASTFileInfo *); | |
5190 | ||
5191 | /** | |
5192 | * \brief Called at the beginning of indexing a translation unit. | |
5193 | */ | |
5194 | CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data, | |
5195 | void *reserved); | |
5196 | ||
5197 | void (*indexDeclaration)(CXClientData client_data, | |
5198 | const CXIdxDeclInfo *); | |
5199 | ||
5200 | /** | |
5201 | * \brief Called to index a reference of an entity. | |
5202 | */ | |
5203 | void (*indexEntityReference)(CXClientData client_data, | |
5204 | const CXIdxEntityRefInfo *); | |
5205 | ||
5206 | } IndexerCallbacks; | |
5207 | ||
5208 | CINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind); | |
5209 | CINDEX_LINKAGE const CXIdxObjCContainerDeclInfo * | |
5210 | clang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *); | |
5211 | ||
5212 | CINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo * | |
5213 | clang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *); | |
5214 | ||
5215 | CINDEX_LINKAGE | |
5216 | const CXIdxObjCCategoryDeclInfo * | |
5217 | clang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *); | |
5218 | ||
5219 | CINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo * | |
5220 | clang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *); | |
5221 | ||
5222 | CINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo * | |
5223 | clang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *); | |
5224 | ||
5225 | CINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo * | |
5226 | clang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *); | |
5227 | ||
5228 | CINDEX_LINKAGE const CXIdxCXXClassDeclInfo * | |
5229 | clang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *); | |
5230 | ||
5231 | /** | |
5232 | * \brief For retrieving a custom CXIdxClientContainer attached to a | |
5233 | * container. | |
5234 | */ | |
5235 | CINDEX_LINKAGE CXIdxClientContainer | |
5236 | clang_index_getClientContainer(const CXIdxContainerInfo *); | |
5237 | ||
5238 | /** | |
5239 | * \brief For setting a custom CXIdxClientContainer attached to a | |
5240 | * container. | |
5241 | */ | |
5242 | CINDEX_LINKAGE void | |
5243 | clang_index_setClientContainer(const CXIdxContainerInfo *,CXIdxClientContainer); | |
5244 | ||
5245 | /** | |
5246 | * \brief For retrieving a custom CXIdxClientEntity attached to an entity. | |
5247 | */ | |
5248 | CINDEX_LINKAGE CXIdxClientEntity | |
5249 | clang_index_getClientEntity(const CXIdxEntityInfo *); | |
5250 | ||
5251 | /** | |
5252 | * \brief For setting a custom CXIdxClientEntity attached to an entity. | |
5253 | */ | |
5254 | CINDEX_LINKAGE void | |
5255 | clang_index_setClientEntity(const CXIdxEntityInfo *, CXIdxClientEntity); | |
5256 | ||
5257 | /** | |
5258 | * \brief An indexing action, to be applied to one or multiple translation units | |
5259 | * but not on concurrent threads. If there are threads doing indexing | |
5260 | * concurrently, they should use different CXIndexAction objects. | |
5261 | */ | |
5262 | typedef void *CXIndexAction; | |
5263 | ||
5264 | /** | |
5265 | * \brief An indexing action, to be applied to one or multiple translation units | |
5266 | * but not on concurrent threads. If there are threads doing indexing | |
5267 | * concurrently, they should use different CXIndexAction objects. | |
5268 | * | |
5269 | * \param CIdx The index object with which the index action will be associated. | |
5270 | */ | |
5271 | CINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx); | |
5272 | ||
5273 | /** | |
5274 | * \brief Destroy the given index action. | |
5275 | * | |
5276 | * The index action must not be destroyed until all of the translation units | |
5277 | * created within that index action have been destroyed. | |
5278 | */ | |
5279 | CINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction); | |
5280 | ||
5281 | typedef enum { | |
5282 | /** | |
5283 | * \brief Used to indicate that no special indexing options are needed. | |
5284 | */ | |
5285 | CXIndexOpt_None = 0x0, | |
5286 | ||
5287 | /** | |
5288 | * \brief Used to indicate that IndexerCallbacks#indexEntityReference should | |
5289 | * be invoked for only one reference of an entity per source file that does | |
5290 | * not also include a declaration/definition of the entity. | |
5291 | */ | |
5292 | CXIndexOpt_SuppressRedundantRefs = 0x1, | |
5293 | ||
5294 | /** | |
5295 | * \brief Function-local symbols should be indexed. If this is not set | |
5296 | * function-local symbols will be ignored. | |
5297 | */ | |
5298 | CXIndexOpt_IndexFunctionLocalSymbols = 0x2, | |
5299 | ||
5300 | /** | |
5301 | * \brief Implicit function/class template instantiations should be indexed. | |
5302 | * If this is not set, implicit instantiations will be ignored. | |
5303 | */ | |
5304 | CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4, | |
5305 | ||
5306 | /** | |
5307 | * \brief Suppress all compiler warnings when parsing for indexing. | |
5308 | */ | |
5309 | CXIndexOpt_SuppressWarnings = 0x8 | |
5310 | } CXIndexOptFlags; | |
5311 | ||
5312 | /** | |
5313 | * \brief Index the given source file and the translation unit corresponding | |
5314 | * to that file via callbacks implemented through #IndexerCallbacks. | |
5315 | * | |
5316 | * \param client_data pointer data supplied by the client, which will | |
5317 | * be passed to the invoked callbacks. | |
5318 | * | |
5319 | * \param index_callbacks Pointer to indexing callbacks that the client | |
5320 | * implements. | |
5321 | * | |
5322 | * \param index_callbacks_size Size of #IndexerCallbacks structure that gets | |
5323 | * passed in index_callbacks. | |
5324 | * | |
5325 | * \param index_options A bitmask of options that affects how indexing is | |
5326 | * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags. | |
5327 | * | |
5328 | * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused | |
5329 | * after indexing is finished. Set to NULL if you do not require it. | |
5330 | * | |
5331 | * \returns If there is a failure from which the there is no recovery, returns | |
5332 | * non-zero, otherwise returns 0. | |
5333 | * | |
5334 | * The rest of the parameters are the same as #clang_parseTranslationUnit. | |
5335 | */ | |
5336 | CINDEX_LINKAGE int clang_indexSourceFile(CXIndexAction, | |
5337 | CXClientData client_data, | |
5338 | IndexerCallbacks *index_callbacks, | |
5339 | unsigned index_callbacks_size, | |
5340 | unsigned index_options, | |
5341 | const char *source_filename, | |
5342 | const char * const *command_line_args, | |
5343 | int num_command_line_args, | |
5344 | struct CXUnsavedFile *unsaved_files, | |
5345 | unsigned num_unsaved_files, | |
5346 | CXTranslationUnit *out_TU, | |
5347 | unsigned TU_options); | |
5348 | ||
5349 | /** | |
5350 | * \brief Index the given translation unit via callbacks implemented through | |
5351 | * #IndexerCallbacks. | |
5352 | * | |
5353 | * The order of callback invocations is not guaranteed to be the same as | |
5354 | * when indexing a source file. The high level order will be: | |
5355 | * | |
5356 | * -Preprocessor callbacks invocations | |
5357 | * -Declaration/reference callbacks invocations | |
5358 | * -Diagnostic callback invocations | |
5359 | * | |
5360 | * The parameters are the same as #clang_indexSourceFile. | |
5361 | * | |
5362 | * \returns If there is a failure from which the there is no recovery, returns | |
5363 | * non-zero, otherwise returns 0. | |
5364 | */ | |
5365 | CINDEX_LINKAGE int clang_indexTranslationUnit(CXIndexAction, | |
5366 | CXClientData client_data, | |
5367 | IndexerCallbacks *index_callbacks, | |
5368 | unsigned index_callbacks_size, | |
5369 | unsigned index_options, | |
5370 | CXTranslationUnit); | |
5371 | ||
5372 | /** | |
5373 | * \brief Retrieve the CXIdxFile, file, line, column, and offset represented by | |
5374 | * the given CXIdxLoc. | |
5375 | * | |
5376 | * If the location refers into a macro expansion, retrieves the | |
5377 | * location of the macro expansion and if it refers into a macro argument | |
5378 | * retrieves the location of the argument. | |
5379 | */ | |
5380 | CINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc, | |
5381 | CXIdxClientFile *indexFile, | |
5382 | CXFile *file, | |
5383 | unsigned *line, | |
5384 | unsigned *column, | |
5385 | unsigned *offset); | |
5386 | ||
5387 | /** | |
5388 | * \brief Retrieve the CXSourceLocation represented by the given CXIdxLoc. | |
5389 | */ | |
5390 | CINDEX_LINKAGE | |
5391 | CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc); | |
5392 | ||
5393 | /** | |
5394 | * @} | |
5395 | */ | |
5396 | ||
5397 | /** | |
5398 | * @} | |
5399 | */ | |
5400 | ||
5401 | #ifdef __cplusplus | |
5402 | } | |
5403 | #endif | |
5404 | #endif | |
5405 |