xref: /freebsd/contrib/llvm-project/clang/include/clang-c/Index.h (revision 38a52bd3b5cac3da6f7f6eef3dd050e6aa08ebb3)
1 /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
2 |*                                                                            *|
3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
4 |* Exceptions.                                                                *|
5 |* See https://llvm.org/LICENSE.txt for license information.                  *|
6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
7 |*                                                                            *|
8 |*===----------------------------------------------------------------------===*|
9 |*                                                                            *|
10 |* This header provides a public interface 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 LLVM_CLANG_C_INDEX_H
17 #define LLVM_CLANG_C_INDEX_H
18 
19 #include <time.h>
20 
21 #include "clang-c/BuildSystem.h"
22 #include "clang-c/CXErrorCode.h"
23 #include "clang-c/CXString.h"
24 #include "clang-c/ExternC.h"
25 #include "clang-c/Platform.h"
26 
27 /**
28  * The version constants for the libclang API.
29  * CINDEX_VERSION_MINOR should increase when there are API additions.
30  * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes.
31  *
32  * The policy about the libclang API was always to keep it source and ABI
33  * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable.
34  */
35 #define CINDEX_VERSION_MAJOR 0
36 #define CINDEX_VERSION_MINOR 62
37 
38 #define CINDEX_VERSION_ENCODE(major, minor) (((major)*10000) + ((minor)*1))
39 
40 #define CINDEX_VERSION                                                         \
41   CINDEX_VERSION_ENCODE(CINDEX_VERSION_MAJOR, CINDEX_VERSION_MINOR)
42 
43 #define CINDEX_VERSION_STRINGIZE_(major, minor) #major "." #minor
44 #define CINDEX_VERSION_STRINGIZE(major, minor)                                 \
45   CINDEX_VERSION_STRINGIZE_(major, minor)
46 
47 #define CINDEX_VERSION_STRING                                                  \
48   CINDEX_VERSION_STRINGIZE(CINDEX_VERSION_MAJOR, CINDEX_VERSION_MINOR)
49 
50 LLVM_CLANG_C_EXTERN_C_BEGIN
51 
52 /** \defgroup CINDEX libclang: C Interface to Clang
53  *
54  * The C Interface to Clang provides a relatively small API that exposes
55  * facilities for parsing source code into an abstract syntax tree (AST),
56  * loading already-parsed ASTs, traversing the AST, associating
57  * physical source locations with elements within the AST, and other
58  * facilities that support Clang-based development tools.
59  *
60  * This C interface to Clang will never provide all of the information
61  * representation stored in Clang's C++ AST, nor should it: the intent is to
62  * maintain an API that is relatively stable from one release to the next,
63  * providing only the basic functionality needed to support development tools.
64  *
65  * To avoid namespace pollution, data types are prefixed with "CX" and
66  * functions are prefixed with "clang_".
67  *
68  * @{
69  */
70 
71 /**
72  * An "index" that consists of a set of translation units that would
73  * typically be linked together into an executable or library.
74  */
75 typedef void *CXIndex;
76 
77 /**
78  * An opaque type representing target information for a given translation
79  * unit.
80  */
81 typedef struct CXTargetInfoImpl *CXTargetInfo;
82 
83 /**
84  * A single translation unit, which resides in an index.
85  */
86 typedef struct CXTranslationUnitImpl *CXTranslationUnit;
87 
88 /**
89  * Opaque pointer representing client data that will be passed through
90  * to various callbacks and visitors.
91  */
92 typedef void *CXClientData;
93 
94 /**
95  * Provides the contents of a file that has not yet been saved to disk.
96  *
97  * Each CXUnsavedFile instance provides the name of a file on the
98  * system along with the current contents of that file that have not
99  * yet been saved to disk.
100  */
101 struct CXUnsavedFile {
102   /**
103    * The file whose contents have not yet been saved.
104    *
105    * This file must already exist in the file system.
106    */
107   const char *Filename;
108 
109   /**
110    * A buffer containing the unsaved contents of this file.
111    */
112   const char *Contents;
113 
114   /**
115    * The length of the unsaved contents of this buffer.
116    */
117   unsigned long Length;
118 };
119 
120 /**
121  * Describes the availability of a particular entity, which indicates
122  * whether the use of this entity will result in a warning or error due to
123  * it being deprecated or unavailable.
124  */
125 enum CXAvailabilityKind {
126   /**
127    * The entity is available.
128    */
129   CXAvailability_Available,
130   /**
131    * The entity is available, but has been deprecated (and its use is
132    * not recommended).
133    */
134   CXAvailability_Deprecated,
135   /**
136    * The entity is not available; any use of it will be an error.
137    */
138   CXAvailability_NotAvailable,
139   /**
140    * The entity is available, but not accessible; any use of it will be
141    * an error.
142    */
143   CXAvailability_NotAccessible
144 };
145 
146 /**
147  * Describes a version number of the form major.minor.subminor.
148  */
149 typedef struct CXVersion {
150   /**
151    * The major version number, e.g., the '10' in '10.7.3'. A negative
152    * value indicates that there is no version number at all.
153    */
154   int Major;
155   /**
156    * The minor version number, e.g., the '7' in '10.7.3'. This value
157    * will be negative if no minor version number was provided, e.g., for
158    * version '10'.
159    */
160   int Minor;
161   /**
162    * The subminor version number, e.g., the '3' in '10.7.3'. This value
163    * will be negative if no minor or subminor version number was provided,
164    * e.g., in version '10' or '10.7'.
165    */
166   int Subminor;
167 } CXVersion;
168 
169 /**
170  * Describes the exception specification of a cursor.
171  *
172  * A negative value indicates that the cursor is not a function declaration.
173  */
174 enum CXCursor_ExceptionSpecificationKind {
175   /**
176    * The cursor has no exception specification.
177    */
178   CXCursor_ExceptionSpecificationKind_None,
179 
180   /**
181    * The cursor has exception specification throw()
182    */
183   CXCursor_ExceptionSpecificationKind_DynamicNone,
184 
185   /**
186    * The cursor has exception specification throw(T1, T2)
187    */
188   CXCursor_ExceptionSpecificationKind_Dynamic,
189 
190   /**
191    * The cursor has exception specification throw(...).
192    */
193   CXCursor_ExceptionSpecificationKind_MSAny,
194 
195   /**
196    * The cursor has exception specification basic noexcept.
197    */
198   CXCursor_ExceptionSpecificationKind_BasicNoexcept,
199 
200   /**
201    * The cursor has exception specification computed noexcept.
202    */
203   CXCursor_ExceptionSpecificationKind_ComputedNoexcept,
204 
205   /**
206    * The exception specification has not yet been evaluated.
207    */
208   CXCursor_ExceptionSpecificationKind_Unevaluated,
209 
210   /**
211    * The exception specification has not yet been instantiated.
212    */
213   CXCursor_ExceptionSpecificationKind_Uninstantiated,
214 
215   /**
216    * The exception specification has not been parsed yet.
217    */
218   CXCursor_ExceptionSpecificationKind_Unparsed,
219 
220   /**
221    * The cursor has a __declspec(nothrow) exception specification.
222    */
223   CXCursor_ExceptionSpecificationKind_NoThrow
224 };
225 
226 /**
227  * Provides a shared context for creating translation units.
228  *
229  * It provides two options:
230  *
231  * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
232  * declarations (when loading any new translation units). A "local" declaration
233  * is one that belongs in the translation unit itself and not in a precompiled
234  * header that was used by the translation unit. If zero, all declarations
235  * will be enumerated.
236  *
237  * Here is an example:
238  *
239  * \code
240  *   // excludeDeclsFromPCH = 1, displayDiagnostics=1
241  *   Idx = clang_createIndex(1, 1);
242  *
243  *   // IndexTest.pch was produced with the following command:
244  *   // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
245  *   TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
246  *
247  *   // This will load all the symbols from 'IndexTest.pch'
248  *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
249  *                       TranslationUnitVisitor, 0);
250  *   clang_disposeTranslationUnit(TU);
251  *
252  *   // This will load all the symbols from 'IndexTest.c', excluding symbols
253  *   // from 'IndexTest.pch'.
254  *   char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
255  *   TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
256  *                                                  0, 0);
257  *   clang_visitChildren(clang_getTranslationUnitCursor(TU),
258  *                       TranslationUnitVisitor, 0);
259  *   clang_disposeTranslationUnit(TU);
260  * \endcode
261  *
262  * This process of creating the 'pch', loading it separately, and using it (via
263  * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
264  * (which gives the indexer the same performance benefit as the compiler).
265  */
266 CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
267                                          int displayDiagnostics);
268 
269 /**
270  * Destroy the given index.
271  *
272  * The index must not be destroyed until all of the translation units created
273  * within that index have been destroyed.
274  */
275 CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
276 
277 typedef enum {
278   /**
279    * Used to indicate that no special CXIndex options are needed.
280    */
281   CXGlobalOpt_None = 0x0,
282 
283   /**
284    * Used to indicate that threads that libclang creates for indexing
285    * purposes should use background priority.
286    *
287    * Affects #clang_indexSourceFile, #clang_indexTranslationUnit,
288    * #clang_parseTranslationUnit, #clang_saveTranslationUnit.
289    */
290   CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1,
291 
292   /**
293    * Used to indicate that threads that libclang creates for editing
294    * purposes should use background priority.
295    *
296    * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt,
297    * #clang_annotateTokens
298    */
299   CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2,
300 
301   /**
302    * Used to indicate that all threads that libclang creates should use
303    * background priority.
304    */
305   CXGlobalOpt_ThreadBackgroundPriorityForAll =
306       CXGlobalOpt_ThreadBackgroundPriorityForIndexing |
307       CXGlobalOpt_ThreadBackgroundPriorityForEditing
308 
309 } CXGlobalOptFlags;
310 
311 /**
312  * Sets general options associated with a CXIndex.
313  *
314  * For example:
315  * \code
316  * CXIndex idx = ...;
317  * clang_CXIndex_setGlobalOptions(idx,
318  *     clang_CXIndex_getGlobalOptions(idx) |
319  *     CXGlobalOpt_ThreadBackgroundPriorityForIndexing);
320  * \endcode
321  *
322  * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags.
323  */
324 CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options);
325 
326 /**
327  * Gets the general options associated with a CXIndex.
328  *
329  * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that
330  * are associated with the given CXIndex object.
331  */
332 CINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex);
333 
334 /**
335  * Sets the invocation emission path option in a CXIndex.
336  *
337  * The invocation emission path specifies a path which will contain log
338  * files for certain libclang invocations. A null value (default) implies that
339  * libclang invocations are not logged..
340  */
341 CINDEX_LINKAGE void
342 clang_CXIndex_setInvocationEmissionPathOption(CXIndex, const char *Path);
343 
344 /**
345  * \defgroup CINDEX_FILES File manipulation routines
346  *
347  * @{
348  */
349 
350 /**
351  * A particular source file that is part of a translation unit.
352  */
353 typedef void *CXFile;
354 
355 /**
356  * Retrieve the complete file and path name of the given file.
357  */
358 CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile);
359 
360 /**
361  * Retrieve the last modification time of the given file.
362  */
363 CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
364 
365 /**
366  * Uniquely identifies a CXFile, that refers to the same underlying file,
367  * across an indexing session.
368  */
369 typedef struct {
370   unsigned long long data[3];
371 } CXFileUniqueID;
372 
373 /**
374  * Retrieve the unique ID for the given \c file.
375  *
376  * \param file the file to get the ID for.
377  * \param outID stores the returned CXFileUniqueID.
378  * \returns If there was a failure getting the unique ID, returns non-zero,
379  * otherwise returns 0.
380  */
381 CINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID);
382 
383 /**
384  * Determine whether the given header is guarded against
385  * multiple inclusions, either with the conventional
386  * \#ifndef/\#define/\#endif macro guards or with \#pragma once.
387  */
388 CINDEX_LINKAGE unsigned clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu,
389                                                            CXFile file);
390 
391 /**
392  * Retrieve a file handle within the given translation unit.
393  *
394  * \param tu the translation unit
395  *
396  * \param file_name the name of the file.
397  *
398  * \returns the file handle for the named file in the translation unit \p tu,
399  * or a NULL file handle if the file was not a part of this translation unit.
400  */
401 CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
402                                     const char *file_name);
403 
404 /**
405  * Retrieve the buffer associated with the given file.
406  *
407  * \param tu the translation unit
408  *
409  * \param file the file for which to retrieve the buffer.
410  *
411  * \param size [out] if non-NULL, will be set to the size of the buffer.
412  *
413  * \returns a pointer to the buffer in memory that holds the contents of
414  * \p file, or a NULL pointer when the file is not loaded.
415  */
416 CINDEX_LINKAGE const char *clang_getFileContents(CXTranslationUnit tu,
417                                                  CXFile file, size_t *size);
418 
419 /**
420  * Returns non-zero if the \c file1 and \c file2 point to the same file,
421  * or they are both NULL.
422  */
423 CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2);
424 
425 /**
426  * Returns the real path name of \c file.
427  *
428  * An empty string may be returned. Use \c clang_getFileName() in that case.
429  */
430 CINDEX_LINKAGE CXString clang_File_tryGetRealPathName(CXFile file);
431 
432 /**
433  * @}
434  */
435 
436 /**
437  * \defgroup CINDEX_LOCATIONS Physical source locations
438  *
439  * Clang represents physical source locations in its abstract syntax tree in
440  * great detail, with file, line, and column information for the majority of
441  * the tokens parsed in the source code. These data types and functions are
442  * used to represent source location information, either for a particular
443  * point in the program or for a range of points in the program, and extract
444  * specific location information from those data types.
445  *
446  * @{
447  */
448 
449 /**
450  * Identifies a specific source location within a translation
451  * unit.
452  *
453  * Use clang_getExpansionLocation() or clang_getSpellingLocation()
454  * to map a source location to a particular file, line, and column.
455  */
456 typedef struct {
457   const void *ptr_data[2];
458   unsigned int_data;
459 } CXSourceLocation;
460 
461 /**
462  * Identifies a half-open character range in the source code.
463  *
464  * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
465  * starting and end locations from a source range, respectively.
466  */
467 typedef struct {
468   const void *ptr_data[2];
469   unsigned begin_int_data;
470   unsigned end_int_data;
471 } CXSourceRange;
472 
473 /**
474  * Retrieve a NULL (invalid) source location.
475  */
476 CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void);
477 
478 /**
479  * Determine whether two source locations, which must refer into
480  * the same translation unit, refer to exactly the same point in the source
481  * code.
482  *
483  * \returns non-zero if the source locations refer to the same location, zero
484  * if they refer to different locations.
485  */
486 CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,
487                                              CXSourceLocation loc2);
488 
489 /**
490  * Retrieves the source location associated with a given file/line/column
491  * in a particular translation unit.
492  */
493 CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu,
494                                                   CXFile file, unsigned line,
495                                                   unsigned column);
496 /**
497  * Retrieves the source location associated with a given character offset
498  * in a particular translation unit.
499  */
500 CINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu,
501                                                            CXFile file,
502                                                            unsigned offset);
503 
504 /**
505  * Returns non-zero if the given source location is in a system header.
506  */
507 CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location);
508 
509 /**
510  * Returns non-zero if the given source location is in the main file of
511  * the corresponding translation unit.
512  */
513 CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location);
514 
515 /**
516  * Retrieve a NULL (invalid) source range.
517  */
518 CINDEX_LINKAGE CXSourceRange clang_getNullRange(void);
519 
520 /**
521  * Retrieve a source range given the beginning and ending source
522  * locations.
523  */
524 CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
525                                             CXSourceLocation end);
526 
527 /**
528  * Determine whether two ranges are equivalent.
529  *
530  * \returns non-zero if the ranges are the same, zero if they differ.
531  */
532 CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1,
533                                           CXSourceRange range2);
534 
535 /**
536  * Returns non-zero if \p range is null.
537  */
538 CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range);
539 
540 /**
541  * Retrieve the file, line, column, and offset represented by
542  * the given source location.
543  *
544  * If the location refers into a macro expansion, retrieves the
545  * location of the macro expansion.
546  *
547  * \param location the location within a source file that will be decomposed
548  * into its parts.
549  *
550  * \param file [out] if non-NULL, will be set to the file to which the given
551  * source location points.
552  *
553  * \param line [out] if non-NULL, will be set to the line to which the given
554  * source location points.
555  *
556  * \param column [out] if non-NULL, will be set to the column to which the given
557  * source location points.
558  *
559  * \param offset [out] if non-NULL, will be set to the offset into the
560  * buffer to which the given source location points.
561  */
562 CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location,
563                                                CXFile *file, unsigned *line,
564                                                unsigned *column,
565                                                unsigned *offset);
566 
567 /**
568  * Retrieve the file, line and column represented by the given source
569  * location, as specified in a # line directive.
570  *
571  * Example: given the following source code in a file somefile.c
572  *
573  * \code
574  * #123 "dummy.c" 1
575  *
576  * static int func(void)
577  * {
578  *     return 0;
579  * }
580  * \endcode
581  *
582  * the location information returned by this function would be
583  *
584  * File: dummy.c Line: 124 Column: 12
585  *
586  * whereas clang_getExpansionLocation would have returned
587  *
588  * File: somefile.c Line: 3 Column: 12
589  *
590  * \param location the location within a source file that will be decomposed
591  * into its parts.
592  *
593  * \param filename [out] if non-NULL, will be set to the filename of the
594  * source location. Note that filenames returned will be for "virtual" files,
595  * which don't necessarily exist on the machine running clang - e.g. when
596  * parsing preprocessed output obtained from a different environment. If
597  * a non-NULL value is passed in, remember to dispose of the returned value
598  * using \c clang_disposeString() once you've finished with it. For an invalid
599  * source location, an empty string is returned.
600  *
601  * \param line [out] if non-NULL, will be set to the line number of the
602  * source location. For an invalid source location, zero is returned.
603  *
604  * \param column [out] if non-NULL, will be set to the column number of the
605  * source location. For an invalid source location, zero is returned.
606  */
607 CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location,
608                                               CXString *filename,
609                                               unsigned *line, unsigned *column);
610 
611 /**
612  * Legacy API to retrieve the file, line, column, and offset represented
613  * by the given source location.
614  *
615  * This interface has been replaced by the newer interface
616  * #clang_getExpansionLocation(). See that interface's documentation for
617  * details.
618  */
619 CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
620                                                    CXFile *file, unsigned *line,
621                                                    unsigned *column,
622                                                    unsigned *offset);
623 
624 /**
625  * Retrieve the file, line, column, and offset represented by
626  * the given source location.
627  *
628  * If the location refers into a macro instantiation, return where the
629  * location was originally spelled in the source file.
630  *
631  * \param location the location within a source file that will be decomposed
632  * into its parts.
633  *
634  * \param file [out] if non-NULL, will be set to the file to which the given
635  * source location points.
636  *
637  * \param line [out] if non-NULL, will be set to the line to which the given
638  * source location points.
639  *
640  * \param column [out] if non-NULL, will be set to the column to which the given
641  * source location points.
642  *
643  * \param offset [out] if non-NULL, will be set to the offset into the
644  * buffer to which the given source location points.
645  */
646 CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location,
647                                               CXFile *file, unsigned *line,
648                                               unsigned *column,
649                                               unsigned *offset);
650 
651 /**
652  * Retrieve the file, line, column, and offset represented by
653  * the given source location.
654  *
655  * If the location refers into a macro expansion, return where the macro was
656  * expanded or where the macro argument was written, if the location points at
657  * a macro argument.
658  *
659  * \param location the location within a source file that will be decomposed
660  * into its parts.
661  *
662  * \param file [out] if non-NULL, will be set to the file to which the given
663  * source location points.
664  *
665  * \param line [out] if non-NULL, will be set to the line to which the given
666  * source location points.
667  *
668  * \param column [out] if non-NULL, will be set to the column to which the given
669  * source location points.
670  *
671  * \param offset [out] if non-NULL, will be set to the offset into the
672  * buffer to which the given source location points.
673  */
674 CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location,
675                                           CXFile *file, unsigned *line,
676                                           unsigned *column, unsigned *offset);
677 
678 /**
679  * Retrieve a source location representing the first character within a
680  * source range.
681  */
682 CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
683 
684 /**
685  * Retrieve a source location representing the last character within a
686  * source range.
687  */
688 CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
689 
690 /**
691  * Identifies an array of ranges.
692  */
693 typedef struct {
694   /** The number of ranges in the \c ranges array. */
695   unsigned count;
696   /**
697    * An array of \c CXSourceRanges.
698    */
699   CXSourceRange *ranges;
700 } CXSourceRangeList;
701 
702 /**
703  * Retrieve all ranges that were skipped by the preprocessor.
704  *
705  * The preprocessor will skip lines when they are surrounded by an
706  * if/ifdef/ifndef directive whose condition does not evaluate to true.
707  */
708 CINDEX_LINKAGE CXSourceRangeList *clang_getSkippedRanges(CXTranslationUnit tu,
709                                                          CXFile file);
710 
711 /**
712  * Retrieve all ranges from all files that were skipped by the
713  * preprocessor.
714  *
715  * The preprocessor will skip lines when they are surrounded by an
716  * if/ifdef/ifndef directive whose condition does not evaluate to true.
717  */
718 CINDEX_LINKAGE CXSourceRangeList *
719 clang_getAllSkippedRanges(CXTranslationUnit tu);
720 
721 /**
722  * Destroy the given \c CXSourceRangeList.
723  */
724 CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges);
725 
726 /**
727  * @}
728  */
729 
730 /**
731  * \defgroup CINDEX_DIAG Diagnostic reporting
732  *
733  * @{
734  */
735 
736 /**
737  * Describes the severity of a particular diagnostic.
738  */
739 enum CXDiagnosticSeverity {
740   /**
741    * A diagnostic that has been suppressed, e.g., by a command-line
742    * option.
743    */
744   CXDiagnostic_Ignored = 0,
745 
746   /**
747    * This diagnostic is a note that should be attached to the
748    * previous (non-note) diagnostic.
749    */
750   CXDiagnostic_Note = 1,
751 
752   /**
753    * This diagnostic indicates suspicious code that may not be
754    * wrong.
755    */
756   CXDiagnostic_Warning = 2,
757 
758   /**
759    * This diagnostic indicates that the code is ill-formed.
760    */
761   CXDiagnostic_Error = 3,
762 
763   /**
764    * This diagnostic indicates that the code is ill-formed such
765    * that future parser recovery is unlikely to produce useful
766    * results.
767    */
768   CXDiagnostic_Fatal = 4
769 };
770 
771 /**
772  * A single diagnostic, containing the diagnostic's severity,
773  * location, text, source ranges, and fix-it hints.
774  */
775 typedef void *CXDiagnostic;
776 
777 /**
778  * A group of CXDiagnostics.
779  */
780 typedef void *CXDiagnosticSet;
781 
782 /**
783  * Determine the number of diagnostics in a CXDiagnosticSet.
784  */
785 CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);
786 
787 /**
788  * Retrieve a diagnostic associated with the given CXDiagnosticSet.
789  *
790  * \param Diags the CXDiagnosticSet to query.
791  * \param Index the zero-based diagnostic number to retrieve.
792  *
793  * \returns the requested diagnostic. This diagnostic must be freed
794  * via a call to \c clang_disposeDiagnostic().
795  */
796 CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,
797                                                      unsigned Index);
798 
799 /**
800  * Describes the kind of error that occurred (if any) in a call to
801  * \c clang_loadDiagnostics.
802  */
803 enum CXLoadDiag_Error {
804   /**
805    * Indicates that no error occurred.
806    */
807   CXLoadDiag_None = 0,
808 
809   /**
810    * Indicates that an unknown error occurred while attempting to
811    * deserialize diagnostics.
812    */
813   CXLoadDiag_Unknown = 1,
814 
815   /**
816    * Indicates that the file containing the serialized diagnostics
817    * could not be opened.
818    */
819   CXLoadDiag_CannotLoad = 2,
820 
821   /**
822    * Indicates that the serialized diagnostics file is invalid or
823    * corrupt.
824    */
825   CXLoadDiag_InvalidFile = 3
826 };
827 
828 /**
829  * Deserialize a set of diagnostics from a Clang diagnostics bitcode
830  * file.
831  *
832  * \param file The name of the file to deserialize.
833  * \param error A pointer to a enum value recording if there was a problem
834  *        deserializing the diagnostics.
835  * \param errorString A pointer to a CXString for recording the error string
836  *        if the file was not successfully loaded.
837  *
838  * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise.  These
839  * diagnostics should be released using clang_disposeDiagnosticSet().
840  */
841 CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(
842     const char *file, enum CXLoadDiag_Error *error, CXString *errorString);
843 
844 /**
845  * Release a CXDiagnosticSet and all of its contained diagnostics.
846  */
847 CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);
848 
849 /**
850  * Retrieve the child diagnostics of a CXDiagnostic.
851  *
852  * This CXDiagnosticSet does not need to be released by
853  * clang_disposeDiagnosticSet.
854  */
855 CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);
856 
857 /**
858  * Determine the number of diagnostics produced for the given
859  * translation unit.
860  */
861 CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit);
862 
863 /**
864  * Retrieve a diagnostic associated with the given translation unit.
865  *
866  * \param Unit the translation unit to query.
867  * \param Index the zero-based diagnostic number to retrieve.
868  *
869  * \returns the requested diagnostic. This diagnostic must be freed
870  * via a call to \c clang_disposeDiagnostic().
871  */
872 CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit,
873                                                 unsigned Index);
874 
875 /**
876  * Retrieve the complete set of diagnostics associated with a
877  *        translation unit.
878  *
879  * \param Unit the translation unit to query.
880  */
881 CINDEX_LINKAGE CXDiagnosticSet
882 clang_getDiagnosticSetFromTU(CXTranslationUnit Unit);
883 
884 /**
885  * Destroy a diagnostic.
886  */
887 CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
888 
889 /**
890  * Options to control the display of diagnostics.
891  *
892  * The values in this enum are meant to be combined to customize the
893  * behavior of \c clang_formatDiagnostic().
894  */
895 enum CXDiagnosticDisplayOptions {
896   /**
897    * Display the source-location information where the
898    * diagnostic was located.
899    *
900    * When set, diagnostics will be prefixed by the file, line, and
901    * (optionally) column to which the diagnostic refers. For example,
902    *
903    * \code
904    * test.c:28: warning: extra tokens at end of #endif directive
905    * \endcode
906    *
907    * This option corresponds to the clang flag \c -fshow-source-location.
908    */
909   CXDiagnostic_DisplaySourceLocation = 0x01,
910 
911   /**
912    * If displaying the source-location information of the
913    * diagnostic, also include the column number.
914    *
915    * This option corresponds to the clang flag \c -fshow-column.
916    */
917   CXDiagnostic_DisplayColumn = 0x02,
918 
919   /**
920    * If displaying the source-location information of the
921    * diagnostic, also include information about source ranges in a
922    * machine-parsable format.
923    *
924    * This option corresponds to the clang flag
925    * \c -fdiagnostics-print-source-range-info.
926    */
927   CXDiagnostic_DisplaySourceRanges = 0x04,
928 
929   /**
930    * Display the option name associated with this diagnostic, if any.
931    *
932    * The option name displayed (e.g., -Wconversion) will be placed in brackets
933    * after the diagnostic text. This option corresponds to the clang flag
934    * \c -fdiagnostics-show-option.
935    */
936   CXDiagnostic_DisplayOption = 0x08,
937 
938   /**
939    * Display the category number associated with this diagnostic, if any.
940    *
941    * The category number is displayed within brackets after the diagnostic text.
942    * This option corresponds to the clang flag
943    * \c -fdiagnostics-show-category=id.
944    */
945   CXDiagnostic_DisplayCategoryId = 0x10,
946 
947   /**
948    * Display the category name associated with this diagnostic, if any.
949    *
950    * The category name is displayed within brackets after the diagnostic text.
951    * This option corresponds to the clang flag
952    * \c -fdiagnostics-show-category=name.
953    */
954   CXDiagnostic_DisplayCategoryName = 0x20
955 };
956 
957 /**
958  * Format the given diagnostic in a manner that is suitable for display.
959  *
960  * This routine will format the given diagnostic to a string, rendering
961  * the diagnostic according to the various options given. The
962  * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
963  * options that most closely mimics the behavior of the clang compiler.
964  *
965  * \param Diagnostic The diagnostic to print.
966  *
967  * \param Options A set of options that control the diagnostic display,
968  * created by combining \c CXDiagnosticDisplayOptions values.
969  *
970  * \returns A new string containing for formatted diagnostic.
971  */
972 CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
973                                                unsigned Options);
974 
975 /**
976  * Retrieve the set of display options most similar to the
977  * default behavior of the clang compiler.
978  *
979  * \returns A set of display options suitable for use with \c
980  * clang_formatDiagnostic().
981  */
982 CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);
983 
984 /**
985  * Determine the severity of the given diagnostic.
986  */
987 CINDEX_LINKAGE enum CXDiagnosticSeverity
988     clang_getDiagnosticSeverity(CXDiagnostic);
989 
990 /**
991  * Retrieve the source location of the given diagnostic.
992  *
993  * This location is where Clang would print the caret ('^') when
994  * displaying the diagnostic on the command line.
995  */
996 CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);
997 
998 /**
999  * Retrieve the text of the given diagnostic.
1000  */
1001 CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);
1002 
1003 /**
1004  * Retrieve the name of the command-line option that enabled this
1005  * diagnostic.
1006  *
1007  * \param Diag The diagnostic to be queried.
1008  *
1009  * \param Disable If non-NULL, will be set to the option that disables this
1010  * diagnostic (if any).
1011  *
1012  * \returns A string that contains the command-line option used to enable this
1013  * warning, such as "-Wconversion" or "-pedantic".
1014  */
1015 CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag,
1016                                                   CXString *Disable);
1017 
1018 /**
1019  * Retrieve the category number for this diagnostic.
1020  *
1021  * Diagnostics can be categorized into groups along with other, related
1022  * diagnostics (e.g., diagnostics under the same warning flag). This routine
1023  * retrieves the category number for the given diagnostic.
1024  *
1025  * \returns The number of the category that contains this diagnostic, or zero
1026  * if this diagnostic is uncategorized.
1027  */
1028 CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);
1029 
1030 /**
1031  * Retrieve the name of a particular diagnostic category.  This
1032  *  is now deprecated.  Use clang_getDiagnosticCategoryText()
1033  *  instead.
1034  *
1035  * \param Category A diagnostic category number, as returned by
1036  * \c clang_getDiagnosticCategory().
1037  *
1038  * \returns The name of the given diagnostic category.
1039  */
1040 CINDEX_DEPRECATED CINDEX_LINKAGE CXString
1041 clang_getDiagnosticCategoryName(unsigned Category);
1042 
1043 /**
1044  * Retrieve the diagnostic category text for a given diagnostic.
1045  *
1046  * \returns The text of the given diagnostic category.
1047  */
1048 CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic);
1049 
1050 /**
1051  * Determine the number of source ranges associated with the given
1052  * diagnostic.
1053  */
1054 CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
1055 
1056 /**
1057  * Retrieve a source range associated with the diagnostic.
1058  *
1059  * A diagnostic's source ranges highlight important elements in the source
1060  * code. On the command line, Clang displays source ranges by
1061  * underlining them with '~' characters.
1062  *
1063  * \param Diagnostic the diagnostic whose range is being extracted.
1064  *
1065  * \param Range the zero-based index specifying which range to
1066  *
1067  * \returns the requested source range.
1068  */
1069 CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
1070                                                       unsigned Range);
1071 
1072 /**
1073  * Determine the number of fix-it hints associated with the
1074  * given diagnostic.
1075  */
1076 CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
1077 
1078 /**
1079  * Retrieve the replacement information for a given fix-it.
1080  *
1081  * Fix-its are described in terms of a source range whose contents
1082  * should be replaced by a string. This approach generalizes over
1083  * three kinds of operations: removal of source code (the range covers
1084  * the code to be removed and the replacement string is empty),
1085  * replacement of source code (the range covers the code to be
1086  * replaced and the replacement string provides the new code), and
1087  * insertion (both the start and end of the range point at the
1088  * insertion location, and the replacement string provides the text to
1089  * insert).
1090  *
1091  * \param Diagnostic The diagnostic whose fix-its are being queried.
1092  *
1093  * \param FixIt The zero-based index of the fix-it.
1094  *
1095  * \param ReplacementRange The source range whose contents will be
1096  * replaced with the returned replacement string. Note that source
1097  * ranges are half-open ranges [a, b), so the source code should be
1098  * replaced from a and up to (but not including) b.
1099  *
1100  * \returns A string containing text that should be replace the source
1101  * code indicated by the \c ReplacementRange.
1102  */
1103 CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(
1104     CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);
1105 
1106 /**
1107  * @}
1108  */
1109 
1110 /**
1111  * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
1112  *
1113  * The routines in this group provide the ability to create and destroy
1114  * translation units from files, either by parsing the contents of the files or
1115  * by reading in a serialized representation of a translation unit.
1116  *
1117  * @{
1118  */
1119 
1120 /**
1121  * Get the original translation unit source file name.
1122  */
1123 CINDEX_LINKAGE CXString
1124 clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
1125 
1126 /**
1127  * Return the CXTranslationUnit for a given source file and the provided
1128  * command line arguments one would pass to the compiler.
1129  *
1130  * Note: The 'source_filename' argument is optional.  If the caller provides a
1131  * NULL pointer, the name of the source file is expected to reside in the
1132  * specified command line arguments.
1133  *
1134  * Note: When encountered in 'clang_command_line_args', the following options
1135  * are ignored:
1136  *
1137  *   '-c'
1138  *   '-emit-ast'
1139  *   '-fsyntax-only'
1140  *   '-o \<output file>'  (both '-o' and '\<output file>' are ignored)
1141  *
1142  * \param CIdx The index object with which the translation unit will be
1143  * associated.
1144  *
1145  * \param source_filename The name of the source file to load, or NULL if the
1146  * source file is included in \p clang_command_line_args.
1147  *
1148  * \param num_clang_command_line_args The number of command-line arguments in
1149  * \p clang_command_line_args.
1150  *
1151  * \param clang_command_line_args The command-line arguments that would be
1152  * passed to the \c clang executable if it were being invoked out-of-process.
1153  * These command-line options will be parsed and will affect how the translation
1154  * unit is parsed. Note that the following options are ignored: '-c',
1155  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'.
1156  *
1157  * \param num_unsaved_files the number of unsaved file entries in \p
1158  * unsaved_files.
1159  *
1160  * \param unsaved_files the files that have not yet been saved to disk
1161  * but may be required for code completion, including the contents of
1162  * those files.  The contents and name of these files (as specified by
1163  * CXUnsavedFile) are copied when necessary, so the client only needs to
1164  * guarantee their validity until the call to this function returns.
1165  */
1166 CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile(
1167     CXIndex CIdx, const char *source_filename, int num_clang_command_line_args,
1168     const char *const *clang_command_line_args, unsigned num_unsaved_files,
1169     struct CXUnsavedFile *unsaved_files);
1170 
1171 /**
1172  * Same as \c clang_createTranslationUnit2, but returns
1173  * the \c CXTranslationUnit instead of an error code.  In case of an error this
1174  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
1175  * error codes.
1176  */
1177 CINDEX_LINKAGE CXTranslationUnit
1178 clang_createTranslationUnit(CXIndex CIdx, const char *ast_filename);
1179 
1180 /**
1181  * Create a translation unit from an AST file (\c -emit-ast).
1182  *
1183  * \param[out] out_TU A non-NULL pointer to store the created
1184  * \c CXTranslationUnit.
1185  *
1186  * \returns Zero on success, otherwise returns an error code.
1187  */
1188 CINDEX_LINKAGE enum CXErrorCode
1189 clang_createTranslationUnit2(CXIndex CIdx, const char *ast_filename,
1190                              CXTranslationUnit *out_TU);
1191 
1192 /**
1193  * Flags that control the creation of translation units.
1194  *
1195  * The enumerators in this enumeration type are meant to be bitwise
1196  * ORed together to specify which options should be used when
1197  * constructing the translation unit.
1198  */
1199 enum CXTranslationUnit_Flags {
1200   /**
1201    * Used to indicate that no special translation-unit options are
1202    * needed.
1203    */
1204   CXTranslationUnit_None = 0x0,
1205 
1206   /**
1207    * Used to indicate that the parser should construct a "detailed"
1208    * preprocessing record, including all macro definitions and instantiations.
1209    *
1210    * Constructing a detailed preprocessing record requires more memory
1211    * and time to parse, since the information contained in the record
1212    * is usually not retained. However, it can be useful for
1213    * applications that require more detailed information about the
1214    * behavior of the preprocessor.
1215    */
1216   CXTranslationUnit_DetailedPreprocessingRecord = 0x01,
1217 
1218   /**
1219    * Used to indicate that the translation unit is incomplete.
1220    *
1221    * When a translation unit is considered "incomplete", semantic
1222    * analysis that is typically performed at the end of the
1223    * translation unit will be suppressed. For example, this suppresses
1224    * the completion of tentative declarations in C and of
1225    * instantiation of implicitly-instantiation function templates in
1226    * C++. This option is typically used when parsing a header with the
1227    * intent of producing a precompiled header.
1228    */
1229   CXTranslationUnit_Incomplete = 0x02,
1230 
1231   /**
1232    * Used to indicate that the translation unit should be built with an
1233    * implicit precompiled header for the preamble.
1234    *
1235    * An implicit precompiled header is used as an optimization when a
1236    * particular translation unit is likely to be reparsed many times
1237    * when the sources aren't changing that often. In this case, an
1238    * implicit precompiled header will be built containing all of the
1239    * initial includes at the top of the main file (what we refer to as
1240    * the "preamble" of the file). In subsequent parses, if the
1241    * preamble or the files in it have not changed, \c
1242    * clang_reparseTranslationUnit() will re-use the implicit
1243    * precompiled header to improve parsing performance.
1244    */
1245   CXTranslationUnit_PrecompiledPreamble = 0x04,
1246 
1247   /**
1248    * Used to indicate that the translation unit should cache some
1249    * code-completion results with each reparse of the source file.
1250    *
1251    * Caching of code-completion results is a performance optimization that
1252    * introduces some overhead to reparsing but improves the performance of
1253    * code-completion operations.
1254    */
1255   CXTranslationUnit_CacheCompletionResults = 0x08,
1256 
1257   /**
1258    * Used to indicate that the translation unit will be serialized with
1259    * \c clang_saveTranslationUnit.
1260    *
1261    * This option is typically used when parsing a header with the intent of
1262    * producing a precompiled header.
1263    */
1264   CXTranslationUnit_ForSerialization = 0x10,
1265 
1266   /**
1267    * DEPRECATED: Enabled chained precompiled preambles in C++.
1268    *
1269    * Note: this is a *temporary* option that is available only while
1270    * we are testing C++ precompiled preamble support. It is deprecated.
1271    */
1272   CXTranslationUnit_CXXChainedPCH = 0x20,
1273 
1274   /**
1275    * Used to indicate that function/method bodies should be skipped while
1276    * parsing.
1277    *
1278    * This option can be used to search for declarations/definitions while
1279    * ignoring the usages.
1280    */
1281   CXTranslationUnit_SkipFunctionBodies = 0x40,
1282 
1283   /**
1284    * Used to indicate that brief documentation comments should be
1285    * included into the set of code completions returned from this translation
1286    * unit.
1287    */
1288   CXTranslationUnit_IncludeBriefCommentsInCodeCompletion = 0x80,
1289 
1290   /**
1291    * Used to indicate that the precompiled preamble should be created on
1292    * the first parse. Otherwise it will be created on the first reparse. This
1293    * trades runtime on the first parse (serializing the preamble takes time) for
1294    * reduced runtime on the second parse (can now reuse the preamble).
1295    */
1296   CXTranslationUnit_CreatePreambleOnFirstParse = 0x100,
1297 
1298   /**
1299    * Do not stop processing when fatal errors are encountered.
1300    *
1301    * When fatal errors are encountered while parsing a translation unit,
1302    * semantic analysis is typically stopped early when compiling code. A common
1303    * source for fatal errors are unresolvable include files. For the
1304    * purposes of an IDE, this is undesirable behavior and as much information
1305    * as possible should be reported. Use this flag to enable this behavior.
1306    */
1307   CXTranslationUnit_KeepGoing = 0x200,
1308 
1309   /**
1310    * Sets the preprocessor in a mode for parsing a single file only.
1311    */
1312   CXTranslationUnit_SingleFileParse = 0x400,
1313 
1314   /**
1315    * Used in combination with CXTranslationUnit_SkipFunctionBodies to
1316    * constrain the skipping of function bodies to the preamble.
1317    *
1318    * The function bodies of the main file are not skipped.
1319    */
1320   CXTranslationUnit_LimitSkipFunctionBodiesToPreamble = 0x800,
1321 
1322   /**
1323    * Used to indicate that attributed types should be included in CXType.
1324    */
1325   CXTranslationUnit_IncludeAttributedTypes = 0x1000,
1326 
1327   /**
1328    * Used to indicate that implicit attributes should be visited.
1329    */
1330   CXTranslationUnit_VisitImplicitAttributes = 0x2000,
1331 
1332   /**
1333    * Used to indicate that non-errors from included files should be ignored.
1334    *
1335    * If set, clang_getDiagnosticSetFromTU() will not report e.g. warnings from
1336    * included files anymore. This speeds up clang_getDiagnosticSetFromTU() for
1337    * the case where these warnings are not of interest, as for an IDE for
1338    * example, which typically shows only the diagnostics in the main file.
1339    */
1340   CXTranslationUnit_IgnoreNonErrorsFromIncludedFiles = 0x4000,
1341 
1342   /**
1343    * Tells the preprocessor not to skip excluded conditional blocks.
1344    */
1345   CXTranslationUnit_RetainExcludedConditionalBlocks = 0x8000
1346 };
1347 
1348 /**
1349  * Returns the set of flags that is suitable for parsing a translation
1350  * unit that is being edited.
1351  *
1352  * The set of flags returned provide options for \c clang_parseTranslationUnit()
1353  * to indicate that the translation unit is likely to be reparsed many times,
1354  * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
1355  * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
1356  * set contains an unspecified set of optimizations (e.g., the precompiled
1357  * preamble) geared toward improving the performance of these routines. The
1358  * set of optimizations enabled may change from one version to the next.
1359  */
1360 CINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void);
1361 
1362 /**
1363  * Same as \c clang_parseTranslationUnit2, but returns
1364  * the \c CXTranslationUnit instead of an error code.  In case of an error this
1365  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
1366  * error codes.
1367  */
1368 CINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(
1369     CXIndex CIdx, const char *source_filename,
1370     const char *const *command_line_args, int num_command_line_args,
1371     struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
1372     unsigned options);
1373 
1374 /**
1375  * Parse the given source file and the translation unit corresponding
1376  * to that file.
1377  *
1378  * This routine is the main entry point for the Clang C API, providing the
1379  * ability to parse a source file into a translation unit that can then be
1380  * queried by other functions in the API. This routine accepts a set of
1381  * command-line arguments so that the compilation can be configured in the same
1382  * way that the compiler is configured on the command line.
1383  *
1384  * \param CIdx The index object with which the translation unit will be
1385  * associated.
1386  *
1387  * \param source_filename The name of the source file to load, or NULL if the
1388  * source file is included in \c command_line_args.
1389  *
1390  * \param command_line_args The command-line arguments that would be
1391  * passed to the \c clang executable if it were being invoked out-of-process.
1392  * These command-line options will be parsed and will affect how the translation
1393  * unit is parsed. Note that the following options are ignored: '-c',
1394  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'.
1395  *
1396  * \param num_command_line_args The number of command-line arguments in
1397  * \c command_line_args.
1398  *
1399  * \param unsaved_files the files that have not yet been saved to disk
1400  * but may be required for parsing, including the contents of
1401  * those files.  The contents and name of these files (as specified by
1402  * CXUnsavedFile) are copied when necessary, so the client only needs to
1403  * guarantee their validity until the call to this function returns.
1404  *
1405  * \param num_unsaved_files the number of unsaved file entries in \p
1406  * unsaved_files.
1407  *
1408  * \param options A bitmask of options that affects how the translation unit
1409  * is managed but not its compilation. This should be a bitwise OR of the
1410  * CXTranslationUnit_XXX flags.
1411  *
1412  * \param[out] out_TU A non-NULL pointer to store the created
1413  * \c CXTranslationUnit, describing the parsed code and containing any
1414  * diagnostics produced by the compiler.
1415  *
1416  * \returns Zero on success, otherwise returns an error code.
1417  */
1418 CINDEX_LINKAGE enum CXErrorCode clang_parseTranslationUnit2(
1419     CXIndex CIdx, const char *source_filename,
1420     const char *const *command_line_args, int num_command_line_args,
1421     struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
1422     unsigned options, CXTranslationUnit *out_TU);
1423 
1424 /**
1425  * Same as clang_parseTranslationUnit2 but requires a full command line
1426  * for \c command_line_args including argv[0]. This is useful if the standard
1427  * library paths are relative to the binary.
1428  */
1429 CINDEX_LINKAGE enum CXErrorCode clang_parseTranslationUnit2FullArgv(
1430     CXIndex CIdx, const char *source_filename,
1431     const char *const *command_line_args, int num_command_line_args,
1432     struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
1433     unsigned options, CXTranslationUnit *out_TU);
1434 
1435 /**
1436  * Flags that control how translation units are saved.
1437  *
1438  * The enumerators in this enumeration type are meant to be bitwise
1439  * ORed together to specify which options should be used when
1440  * saving the translation unit.
1441  */
1442 enum CXSaveTranslationUnit_Flags {
1443   /**
1444    * Used to indicate that no special saving options are needed.
1445    */
1446   CXSaveTranslationUnit_None = 0x0
1447 };
1448 
1449 /**
1450  * Returns the set of flags that is suitable for saving a translation
1451  * unit.
1452  *
1453  * The set of flags returned provide options for
1454  * \c clang_saveTranslationUnit() by default. The returned flag
1455  * set contains an unspecified set of options that save translation units with
1456  * the most commonly-requested data.
1457  */
1458 CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU);
1459 
1460 /**
1461  * Describes the kind of error that occurred (if any) in a call to
1462  * \c clang_saveTranslationUnit().
1463  */
1464 enum CXSaveError {
1465   /**
1466    * Indicates that no error occurred while saving a translation unit.
1467    */
1468   CXSaveError_None = 0,
1469 
1470   /**
1471    * Indicates that an unknown error occurred while attempting to save
1472    * the file.
1473    *
1474    * This error typically indicates that file I/O failed when attempting to
1475    * write the file.
1476    */
1477   CXSaveError_Unknown = 1,
1478 
1479   /**
1480    * Indicates that errors during translation prevented this attempt
1481    * to save the translation unit.
1482    *
1483    * Errors that prevent the translation unit from being saved can be
1484    * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic().
1485    */
1486   CXSaveError_TranslationErrors = 2,
1487 
1488   /**
1489    * Indicates that the translation unit to be saved was somehow
1490    * invalid (e.g., NULL).
1491    */
1492   CXSaveError_InvalidTU = 3
1493 };
1494 
1495 /**
1496  * Saves a translation unit into a serialized representation of
1497  * that translation unit on disk.
1498  *
1499  * Any translation unit that was parsed without error can be saved
1500  * into a file. The translation unit can then be deserialized into a
1501  * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
1502  * if it is an incomplete translation unit that corresponds to a
1503  * header, used as a precompiled header when parsing other translation
1504  * units.
1505  *
1506  * \param TU The translation unit to save.
1507  *
1508  * \param FileName The file to which the translation unit will be saved.
1509  *
1510  * \param options A bitmask of options that affects how the translation unit
1511  * is saved. This should be a bitwise OR of the
1512  * CXSaveTranslationUnit_XXX flags.
1513  *
1514  * \returns A value that will match one of the enumerators of the CXSaveError
1515  * enumeration. Zero (CXSaveError_None) indicates that the translation unit was
1516  * saved successfully, while a non-zero value indicates that a problem occurred.
1517  */
1518 CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
1519                                              const char *FileName,
1520                                              unsigned options);
1521 
1522 /**
1523  * Suspend a translation unit in order to free memory associated with it.
1524  *
1525  * A suspended translation unit uses significantly less memory but on the other
1526  * side does not support any other calls than \c clang_reparseTranslationUnit
1527  * to resume it or \c clang_disposeTranslationUnit to dispose it completely.
1528  */
1529 CINDEX_LINKAGE unsigned clang_suspendTranslationUnit(CXTranslationUnit);
1530 
1531 /**
1532  * Destroy the specified CXTranslationUnit object.
1533  */
1534 CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
1535 
1536 /**
1537  * Flags that control the reparsing of translation units.
1538  *
1539  * The enumerators in this enumeration type are meant to be bitwise
1540  * ORed together to specify which options should be used when
1541  * reparsing the translation unit.
1542  */
1543 enum CXReparse_Flags {
1544   /**
1545    * Used to indicate that no special reparsing options are needed.
1546    */
1547   CXReparse_None = 0x0
1548 };
1549 
1550 /**
1551  * Returns the set of flags that is suitable for reparsing a translation
1552  * unit.
1553  *
1554  * The set of flags returned provide options for
1555  * \c clang_reparseTranslationUnit() by default. The returned flag
1556  * set contains an unspecified set of optimizations geared toward common uses
1557  * of reparsing. The set of optimizations enabled may change from one version
1558  * to the next.
1559  */
1560 CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
1561 
1562 /**
1563  * Reparse the source files that produced this translation unit.
1564  *
1565  * This routine can be used to re-parse the source files that originally
1566  * created the given translation unit, for example because those source files
1567  * have changed (either on disk or as passed via \p unsaved_files). The
1568  * source code will be reparsed with the same command-line options as it
1569  * was originally parsed.
1570  *
1571  * Reparsing a translation unit invalidates all cursors and source locations
1572  * that refer into that translation unit. This makes reparsing a translation
1573  * unit semantically equivalent to destroying the translation unit and then
1574  * creating a new translation unit with the same command-line arguments.
1575  * However, it may be more efficient to reparse a translation
1576  * unit using this routine.
1577  *
1578  * \param TU The translation unit whose contents will be re-parsed. The
1579  * translation unit must originally have been built with
1580  * \c clang_createTranslationUnitFromSourceFile().
1581  *
1582  * \param num_unsaved_files The number of unsaved file entries in \p
1583  * unsaved_files.
1584  *
1585  * \param unsaved_files The files that have not yet been saved to disk
1586  * but may be required for parsing, including the contents of
1587  * those files.  The contents and name of these files (as specified by
1588  * CXUnsavedFile) are copied when necessary, so the client only needs to
1589  * guarantee their validity until the call to this function returns.
1590  *
1591  * \param options A bitset of options composed of the flags in CXReparse_Flags.
1592  * The function \c clang_defaultReparseOptions() produces a default set of
1593  * options recommended for most uses, based on the translation unit.
1594  *
1595  * \returns 0 if the sources could be reparsed.  A non-zero error code will be
1596  * returned if reparsing was impossible, such that the translation unit is
1597  * invalid. In such cases, the only valid call for \c TU is
1598  * \c clang_disposeTranslationUnit(TU).  The error codes returned by this
1599  * routine are described by the \c CXErrorCode enum.
1600  */
1601 CINDEX_LINKAGE int
1602 clang_reparseTranslationUnit(CXTranslationUnit TU, unsigned num_unsaved_files,
1603                              struct CXUnsavedFile *unsaved_files,
1604                              unsigned options);
1605 
1606 /**
1607  * Categorizes how memory is being used by a translation unit.
1608  */
1609 enum CXTUResourceUsageKind {
1610   CXTUResourceUsage_AST = 1,
1611   CXTUResourceUsage_Identifiers = 2,
1612   CXTUResourceUsage_Selectors = 3,
1613   CXTUResourceUsage_GlobalCompletionResults = 4,
1614   CXTUResourceUsage_SourceManagerContentCache = 5,
1615   CXTUResourceUsage_AST_SideTables = 6,
1616   CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7,
1617   CXTUResourceUsage_SourceManager_Membuffer_MMap = 8,
1618   CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9,
1619   CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10,
1620   CXTUResourceUsage_Preprocessor = 11,
1621   CXTUResourceUsage_PreprocessingRecord = 12,
1622   CXTUResourceUsage_SourceManager_DataStructures = 13,
1623   CXTUResourceUsage_Preprocessor_HeaderSearch = 14,
1624   CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST,
1625   CXTUResourceUsage_MEMORY_IN_BYTES_END =
1626       CXTUResourceUsage_Preprocessor_HeaderSearch,
1627 
1628   CXTUResourceUsage_First = CXTUResourceUsage_AST,
1629   CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch
1630 };
1631 
1632 /**
1633  * Returns the human-readable null-terminated C string that represents
1634  *  the name of the memory category.  This string should never be freed.
1635  */
1636 CINDEX_LINKAGE
1637 const char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind);
1638 
1639 typedef struct CXTUResourceUsageEntry {
1640   /* The memory usage category. */
1641   enum CXTUResourceUsageKind kind;
1642   /* Amount of resources used.
1643       The units will depend on the resource kind. */
1644   unsigned long amount;
1645 } CXTUResourceUsageEntry;
1646 
1647 /**
1648  * The memory usage of a CXTranslationUnit, broken into categories.
1649  */
1650 typedef struct CXTUResourceUsage {
1651   /* Private data member, used for queries. */
1652   void *data;
1653 
1654   /* The number of entries in the 'entries' array. */
1655   unsigned numEntries;
1656 
1657   /* An array of key-value pairs, representing the breakdown of memory
1658             usage. */
1659   CXTUResourceUsageEntry *entries;
1660 
1661 } CXTUResourceUsage;
1662 
1663 /**
1664  * Return the memory usage of a translation unit.  This object
1665  *  should be released with clang_disposeCXTUResourceUsage().
1666  */
1667 CINDEX_LINKAGE CXTUResourceUsage
1668 clang_getCXTUResourceUsage(CXTranslationUnit TU);
1669 
1670 CINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage);
1671 
1672 /**
1673  * Get target information for this translation unit.
1674  *
1675  * The CXTargetInfo object cannot outlive the CXTranslationUnit object.
1676  */
1677 CINDEX_LINKAGE CXTargetInfo
1678 clang_getTranslationUnitTargetInfo(CXTranslationUnit CTUnit);
1679 
1680 /**
1681  * Destroy the CXTargetInfo object.
1682  */
1683 CINDEX_LINKAGE void clang_TargetInfo_dispose(CXTargetInfo Info);
1684 
1685 /**
1686  * Get the normalized target triple as a string.
1687  *
1688  * Returns the empty string in case of any error.
1689  */
1690 CINDEX_LINKAGE CXString clang_TargetInfo_getTriple(CXTargetInfo Info);
1691 
1692 /**
1693  * Get the pointer width of the target in bits.
1694  *
1695  * Returns -1 in case of error.
1696  */
1697 CINDEX_LINKAGE int clang_TargetInfo_getPointerWidth(CXTargetInfo Info);
1698 
1699 /**
1700  * @}
1701  */
1702 
1703 /**
1704  * Describes the kind of entity that a cursor refers to.
1705  */
1706 enum CXCursorKind {
1707   /* Declarations */
1708   /**
1709    * A declaration whose specific kind is not exposed via this
1710    * interface.
1711    *
1712    * Unexposed declarations have the same operations as any other kind
1713    * of declaration; one can extract their location information,
1714    * spelling, find their definitions, etc. However, the specific kind
1715    * of the declaration is not reported.
1716    */
1717   CXCursor_UnexposedDecl = 1,
1718   /** A C or C++ struct. */
1719   CXCursor_StructDecl = 2,
1720   /** A C or C++ union. */
1721   CXCursor_UnionDecl = 3,
1722   /** A C++ class. */
1723   CXCursor_ClassDecl = 4,
1724   /** An enumeration. */
1725   CXCursor_EnumDecl = 5,
1726   /**
1727    * A field (in C) or non-static data member (in C++) in a
1728    * struct, union, or C++ class.
1729    */
1730   CXCursor_FieldDecl = 6,
1731   /** An enumerator constant. */
1732   CXCursor_EnumConstantDecl = 7,
1733   /** A function. */
1734   CXCursor_FunctionDecl = 8,
1735   /** A variable. */
1736   CXCursor_VarDecl = 9,
1737   /** A function or method parameter. */
1738   CXCursor_ParmDecl = 10,
1739   /** An Objective-C \@interface. */
1740   CXCursor_ObjCInterfaceDecl = 11,
1741   /** An Objective-C \@interface for a category. */
1742   CXCursor_ObjCCategoryDecl = 12,
1743   /** An Objective-C \@protocol declaration. */
1744   CXCursor_ObjCProtocolDecl = 13,
1745   /** An Objective-C \@property declaration. */
1746   CXCursor_ObjCPropertyDecl = 14,
1747   /** An Objective-C instance variable. */
1748   CXCursor_ObjCIvarDecl = 15,
1749   /** An Objective-C instance method. */
1750   CXCursor_ObjCInstanceMethodDecl = 16,
1751   /** An Objective-C class method. */
1752   CXCursor_ObjCClassMethodDecl = 17,
1753   /** An Objective-C \@implementation. */
1754   CXCursor_ObjCImplementationDecl = 18,
1755   /** An Objective-C \@implementation for a category. */
1756   CXCursor_ObjCCategoryImplDecl = 19,
1757   /** A typedef. */
1758   CXCursor_TypedefDecl = 20,
1759   /** A C++ class method. */
1760   CXCursor_CXXMethod = 21,
1761   /** A C++ namespace. */
1762   CXCursor_Namespace = 22,
1763   /** A linkage specification, e.g. 'extern "C"'. */
1764   CXCursor_LinkageSpec = 23,
1765   /** A C++ constructor. */
1766   CXCursor_Constructor = 24,
1767   /** A C++ destructor. */
1768   CXCursor_Destructor = 25,
1769   /** A C++ conversion function. */
1770   CXCursor_ConversionFunction = 26,
1771   /** A C++ template type parameter. */
1772   CXCursor_TemplateTypeParameter = 27,
1773   /** A C++ non-type template parameter. */
1774   CXCursor_NonTypeTemplateParameter = 28,
1775   /** A C++ template template parameter. */
1776   CXCursor_TemplateTemplateParameter = 29,
1777   /** A C++ function template. */
1778   CXCursor_FunctionTemplate = 30,
1779   /** A C++ class template. */
1780   CXCursor_ClassTemplate = 31,
1781   /** A C++ class template partial specialization. */
1782   CXCursor_ClassTemplatePartialSpecialization = 32,
1783   /** A C++ namespace alias declaration. */
1784   CXCursor_NamespaceAlias = 33,
1785   /** A C++ using directive. */
1786   CXCursor_UsingDirective = 34,
1787   /** A C++ using declaration. */
1788   CXCursor_UsingDeclaration = 35,
1789   /** A C++ alias declaration */
1790   CXCursor_TypeAliasDecl = 36,
1791   /** An Objective-C \@synthesize definition. */
1792   CXCursor_ObjCSynthesizeDecl = 37,
1793   /** An Objective-C \@dynamic definition. */
1794   CXCursor_ObjCDynamicDecl = 38,
1795   /** An access specifier. */
1796   CXCursor_CXXAccessSpecifier = 39,
1797 
1798   CXCursor_FirstDecl = CXCursor_UnexposedDecl,
1799   CXCursor_LastDecl = CXCursor_CXXAccessSpecifier,
1800 
1801   /* References */
1802   CXCursor_FirstRef = 40, /* Decl references */
1803   CXCursor_ObjCSuperClassRef = 40,
1804   CXCursor_ObjCProtocolRef = 41,
1805   CXCursor_ObjCClassRef = 42,
1806   /**
1807    * A reference to a type declaration.
1808    *
1809    * A type reference occurs anywhere where a type is named but not
1810    * declared. For example, given:
1811    *
1812    * \code
1813    * typedef unsigned size_type;
1814    * size_type size;
1815    * \endcode
1816    *
1817    * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
1818    * while the type of the variable "size" is referenced. The cursor
1819    * referenced by the type of size is the typedef for size_type.
1820    */
1821   CXCursor_TypeRef = 43,
1822   CXCursor_CXXBaseSpecifier = 44,
1823   /**
1824    * A reference to a class template, function template, template
1825    * template parameter, or class template partial specialization.
1826    */
1827   CXCursor_TemplateRef = 45,
1828   /**
1829    * A reference to a namespace or namespace alias.
1830    */
1831   CXCursor_NamespaceRef = 46,
1832   /**
1833    * A reference to a member of a struct, union, or class that occurs in
1834    * some non-expression context, e.g., a designated initializer.
1835    */
1836   CXCursor_MemberRef = 47,
1837   /**
1838    * A reference to a labeled statement.
1839    *
1840    * This cursor kind is used to describe the jump to "start_over" in the
1841    * goto statement in the following example:
1842    *
1843    * \code
1844    *   start_over:
1845    *     ++counter;
1846    *
1847    *     goto start_over;
1848    * \endcode
1849    *
1850    * A label reference cursor refers to a label statement.
1851    */
1852   CXCursor_LabelRef = 48,
1853 
1854   /**
1855    * A reference to a set of overloaded functions or function templates
1856    * that has not yet been resolved to a specific function or function template.
1857    *
1858    * An overloaded declaration reference cursor occurs in C++ templates where
1859    * a dependent name refers to a function. For example:
1860    *
1861    * \code
1862    * template<typename T> void swap(T&, T&);
1863    *
1864    * struct X { ... };
1865    * void swap(X&, X&);
1866    *
1867    * template<typename T>
1868    * void reverse(T* first, T* last) {
1869    *   while (first < last - 1) {
1870    *     swap(*first, *--last);
1871    *     ++first;
1872    *   }
1873    * }
1874    *
1875    * struct Y { };
1876    * void swap(Y&, Y&);
1877    * \endcode
1878    *
1879    * Here, the identifier "swap" is associated with an overloaded declaration
1880    * reference. In the template definition, "swap" refers to either of the two
1881    * "swap" functions declared above, so both results will be available. At
1882    * instantiation time, "swap" may also refer to other functions found via
1883    * argument-dependent lookup (e.g., the "swap" function at the end of the
1884    * example).
1885    *
1886    * The functions \c clang_getNumOverloadedDecls() and
1887    * \c clang_getOverloadedDecl() can be used to retrieve the definitions
1888    * referenced by this cursor.
1889    */
1890   CXCursor_OverloadedDeclRef = 49,
1891 
1892   /**
1893    * A reference to a variable that occurs in some non-expression
1894    * context, e.g., a C++ lambda capture list.
1895    */
1896   CXCursor_VariableRef = 50,
1897 
1898   CXCursor_LastRef = CXCursor_VariableRef,
1899 
1900   /* Error conditions */
1901   CXCursor_FirstInvalid = 70,
1902   CXCursor_InvalidFile = 70,
1903   CXCursor_NoDeclFound = 71,
1904   CXCursor_NotImplemented = 72,
1905   CXCursor_InvalidCode = 73,
1906   CXCursor_LastInvalid = CXCursor_InvalidCode,
1907 
1908   /* Expressions */
1909   CXCursor_FirstExpr = 100,
1910 
1911   /**
1912    * An expression whose specific kind is not exposed via this
1913    * interface.
1914    *
1915    * Unexposed expressions have the same operations as any other kind
1916    * of expression; one can extract their location information,
1917    * spelling, children, etc. However, the specific kind of the
1918    * expression is not reported.
1919    */
1920   CXCursor_UnexposedExpr = 100,
1921 
1922   /**
1923    * An expression that refers to some value declaration, such
1924    * as a function, variable, or enumerator.
1925    */
1926   CXCursor_DeclRefExpr = 101,
1927 
1928   /**
1929    * An expression that refers to a member of a struct, union,
1930    * class, Objective-C class, etc.
1931    */
1932   CXCursor_MemberRefExpr = 102,
1933 
1934   /** An expression that calls a function. */
1935   CXCursor_CallExpr = 103,
1936 
1937   /** An expression that sends a message to an Objective-C
1938    object or class. */
1939   CXCursor_ObjCMessageExpr = 104,
1940 
1941   /** An expression that represents a block literal. */
1942   CXCursor_BlockExpr = 105,
1943 
1944   /** An integer literal.
1945    */
1946   CXCursor_IntegerLiteral = 106,
1947 
1948   /** A floating point number literal.
1949    */
1950   CXCursor_FloatingLiteral = 107,
1951 
1952   /** An imaginary number literal.
1953    */
1954   CXCursor_ImaginaryLiteral = 108,
1955 
1956   /** A string literal.
1957    */
1958   CXCursor_StringLiteral = 109,
1959 
1960   /** A character literal.
1961    */
1962   CXCursor_CharacterLiteral = 110,
1963 
1964   /** A parenthesized expression, e.g. "(1)".
1965    *
1966    * This AST node is only formed if full location information is requested.
1967    */
1968   CXCursor_ParenExpr = 111,
1969 
1970   /** This represents the unary-expression's (except sizeof and
1971    * alignof).
1972    */
1973   CXCursor_UnaryOperator = 112,
1974 
1975   /** [C99 6.5.2.1] Array Subscripting.
1976    */
1977   CXCursor_ArraySubscriptExpr = 113,
1978 
1979   /** A builtin binary operation expression such as "x + y" or
1980    * "x <= y".
1981    */
1982   CXCursor_BinaryOperator = 114,
1983 
1984   /** Compound assignment such as "+=".
1985    */
1986   CXCursor_CompoundAssignOperator = 115,
1987 
1988   /** The ?: ternary operator.
1989    */
1990   CXCursor_ConditionalOperator = 116,
1991 
1992   /** An explicit cast in C (C99 6.5.4) or a C-style cast in C++
1993    * (C++ [expr.cast]), which uses the syntax (Type)expr.
1994    *
1995    * For example: (int)f.
1996    */
1997   CXCursor_CStyleCastExpr = 117,
1998 
1999   /** [C99 6.5.2.5]
2000    */
2001   CXCursor_CompoundLiteralExpr = 118,
2002 
2003   /** Describes an C or C++ initializer list.
2004    */
2005   CXCursor_InitListExpr = 119,
2006 
2007   /** The GNU address of label extension, representing &&label.
2008    */
2009   CXCursor_AddrLabelExpr = 120,
2010 
2011   /** This is the GNU Statement Expression extension: ({int X=4; X;})
2012    */
2013   CXCursor_StmtExpr = 121,
2014 
2015   /** Represents a C11 generic selection.
2016    */
2017   CXCursor_GenericSelectionExpr = 122,
2018 
2019   /** Implements the GNU __null extension, which is a name for a null
2020    * pointer constant that has integral type (e.g., int or long) and is the same
2021    * size and alignment as a pointer.
2022    *
2023    * The __null extension is typically only used by system headers, which define
2024    * NULL as __null in C++ rather than using 0 (which is an integer that may not
2025    * match the size of a pointer).
2026    */
2027   CXCursor_GNUNullExpr = 123,
2028 
2029   /** C++'s static_cast<> expression.
2030    */
2031   CXCursor_CXXStaticCastExpr = 124,
2032 
2033   /** C++'s dynamic_cast<> expression.
2034    */
2035   CXCursor_CXXDynamicCastExpr = 125,
2036 
2037   /** C++'s reinterpret_cast<> expression.
2038    */
2039   CXCursor_CXXReinterpretCastExpr = 126,
2040 
2041   /** C++'s const_cast<> expression.
2042    */
2043   CXCursor_CXXConstCastExpr = 127,
2044 
2045   /** Represents an explicit C++ type conversion that uses "functional"
2046    * notion (C++ [expr.type.conv]).
2047    *
2048    * Example:
2049    * \code
2050    *   x = int(0.5);
2051    * \endcode
2052    */
2053   CXCursor_CXXFunctionalCastExpr = 128,
2054 
2055   /** A C++ typeid expression (C++ [expr.typeid]).
2056    */
2057   CXCursor_CXXTypeidExpr = 129,
2058 
2059   /** [C++ 2.13.5] C++ Boolean Literal.
2060    */
2061   CXCursor_CXXBoolLiteralExpr = 130,
2062 
2063   /** [C++0x 2.14.7] C++ Pointer Literal.
2064    */
2065   CXCursor_CXXNullPtrLiteralExpr = 131,
2066 
2067   /** Represents the "this" expression in C++
2068    */
2069   CXCursor_CXXThisExpr = 132,
2070 
2071   /** [C++ 15] C++ Throw Expression.
2072    *
2073    * This handles 'throw' and 'throw' assignment-expression. When
2074    * assignment-expression isn't present, Op will be null.
2075    */
2076   CXCursor_CXXThrowExpr = 133,
2077 
2078   /** A new expression for memory allocation and constructor calls, e.g:
2079    * "new CXXNewExpr(foo)".
2080    */
2081   CXCursor_CXXNewExpr = 134,
2082 
2083   /** A delete expression for memory deallocation and destructor calls,
2084    * e.g. "delete[] pArray".
2085    */
2086   CXCursor_CXXDeleteExpr = 135,
2087 
2088   /** A unary expression. (noexcept, sizeof, or other traits)
2089    */
2090   CXCursor_UnaryExpr = 136,
2091 
2092   /** An Objective-C string literal i.e. @"foo".
2093    */
2094   CXCursor_ObjCStringLiteral = 137,
2095 
2096   /** An Objective-C \@encode expression.
2097    */
2098   CXCursor_ObjCEncodeExpr = 138,
2099 
2100   /** An Objective-C \@selector expression.
2101    */
2102   CXCursor_ObjCSelectorExpr = 139,
2103 
2104   /** An Objective-C \@protocol expression.
2105    */
2106   CXCursor_ObjCProtocolExpr = 140,
2107 
2108   /** An Objective-C "bridged" cast expression, which casts between
2109    * Objective-C pointers and C pointers, transferring ownership in the process.
2110    *
2111    * \code
2112    *   NSString *str = (__bridge_transfer NSString *)CFCreateString();
2113    * \endcode
2114    */
2115   CXCursor_ObjCBridgedCastExpr = 141,
2116 
2117   /** Represents a C++0x pack expansion that produces a sequence of
2118    * expressions.
2119    *
2120    * A pack expansion expression contains a pattern (which itself is an
2121    * expression) followed by an ellipsis. For example:
2122    *
2123    * \code
2124    * template<typename F, typename ...Types>
2125    * void forward(F f, Types &&...args) {
2126    *  f(static_cast<Types&&>(args)...);
2127    * }
2128    * \endcode
2129    */
2130   CXCursor_PackExpansionExpr = 142,
2131 
2132   /** Represents an expression that computes the length of a parameter
2133    * pack.
2134    *
2135    * \code
2136    * template<typename ...Types>
2137    * struct count {
2138    *   static const unsigned value = sizeof...(Types);
2139    * };
2140    * \endcode
2141    */
2142   CXCursor_SizeOfPackExpr = 143,
2143 
2144   /* Represents a C++ lambda expression that produces a local function
2145    * object.
2146    *
2147    * \code
2148    * void abssort(float *x, unsigned N) {
2149    *   std::sort(x, x + N,
2150    *             [](float a, float b) {
2151    *               return std::abs(a) < std::abs(b);
2152    *             });
2153    * }
2154    * \endcode
2155    */
2156   CXCursor_LambdaExpr = 144,
2157 
2158   /** Objective-c Boolean Literal.
2159    */
2160   CXCursor_ObjCBoolLiteralExpr = 145,
2161 
2162   /** Represents the "self" expression in an Objective-C method.
2163    */
2164   CXCursor_ObjCSelfExpr = 146,
2165 
2166   /** OpenMP 5.0 [2.1.5, Array Section].
2167    */
2168   CXCursor_OMPArraySectionExpr = 147,
2169 
2170   /** Represents an @available(...) check.
2171    */
2172   CXCursor_ObjCAvailabilityCheckExpr = 148,
2173 
2174   /**
2175    * Fixed point literal
2176    */
2177   CXCursor_FixedPointLiteral = 149,
2178 
2179   /** OpenMP 5.0 [2.1.4, Array Shaping].
2180    */
2181   CXCursor_OMPArrayShapingExpr = 150,
2182 
2183   /**
2184    * OpenMP 5.0 [2.1.6 Iterators]
2185    */
2186   CXCursor_OMPIteratorExpr = 151,
2187 
2188   /** OpenCL's addrspace_cast<> expression.
2189    */
2190   CXCursor_CXXAddrspaceCastExpr = 152,
2191 
2192   CXCursor_LastExpr = CXCursor_CXXAddrspaceCastExpr,
2193 
2194   /* Statements */
2195   CXCursor_FirstStmt = 200,
2196   /**
2197    * A statement whose specific kind is not exposed via this
2198    * interface.
2199    *
2200    * Unexposed statements have the same operations as any other kind of
2201    * statement; one can extract their location information, spelling,
2202    * children, etc. However, the specific kind of the statement is not
2203    * reported.
2204    */
2205   CXCursor_UnexposedStmt = 200,
2206 
2207   /** A labelled statement in a function.
2208    *
2209    * This cursor kind is used to describe the "start_over:" label statement in
2210    * the following example:
2211    *
2212    * \code
2213    *   start_over:
2214    *     ++counter;
2215    * \endcode
2216    *
2217    */
2218   CXCursor_LabelStmt = 201,
2219 
2220   /** A group of statements like { stmt stmt }.
2221    *
2222    * This cursor kind is used to describe compound statements, e.g. function
2223    * bodies.
2224    */
2225   CXCursor_CompoundStmt = 202,
2226 
2227   /** A case statement.
2228    */
2229   CXCursor_CaseStmt = 203,
2230 
2231   /** A default statement.
2232    */
2233   CXCursor_DefaultStmt = 204,
2234 
2235   /** An if statement
2236    */
2237   CXCursor_IfStmt = 205,
2238 
2239   /** A switch statement.
2240    */
2241   CXCursor_SwitchStmt = 206,
2242 
2243   /** A while statement.
2244    */
2245   CXCursor_WhileStmt = 207,
2246 
2247   /** A do statement.
2248    */
2249   CXCursor_DoStmt = 208,
2250 
2251   /** A for statement.
2252    */
2253   CXCursor_ForStmt = 209,
2254 
2255   /** A goto statement.
2256    */
2257   CXCursor_GotoStmt = 210,
2258 
2259   /** An indirect goto statement.
2260    */
2261   CXCursor_IndirectGotoStmt = 211,
2262 
2263   /** A continue statement.
2264    */
2265   CXCursor_ContinueStmt = 212,
2266 
2267   /** A break statement.
2268    */
2269   CXCursor_BreakStmt = 213,
2270 
2271   /** A return statement.
2272    */
2273   CXCursor_ReturnStmt = 214,
2274 
2275   /** A GCC inline assembly statement extension.
2276    */
2277   CXCursor_GCCAsmStmt = 215,
2278   CXCursor_AsmStmt = CXCursor_GCCAsmStmt,
2279 
2280   /** Objective-C's overall \@try-\@catch-\@finally statement.
2281    */
2282   CXCursor_ObjCAtTryStmt = 216,
2283 
2284   /** Objective-C's \@catch statement.
2285    */
2286   CXCursor_ObjCAtCatchStmt = 217,
2287 
2288   /** Objective-C's \@finally statement.
2289    */
2290   CXCursor_ObjCAtFinallyStmt = 218,
2291 
2292   /** Objective-C's \@throw statement.
2293    */
2294   CXCursor_ObjCAtThrowStmt = 219,
2295 
2296   /** Objective-C's \@synchronized statement.
2297    */
2298   CXCursor_ObjCAtSynchronizedStmt = 220,
2299 
2300   /** Objective-C's autorelease pool statement.
2301    */
2302   CXCursor_ObjCAutoreleasePoolStmt = 221,
2303 
2304   /** Objective-C's collection statement.
2305    */
2306   CXCursor_ObjCForCollectionStmt = 222,
2307 
2308   /** C++'s catch statement.
2309    */
2310   CXCursor_CXXCatchStmt = 223,
2311 
2312   /** C++'s try statement.
2313    */
2314   CXCursor_CXXTryStmt = 224,
2315 
2316   /** C++'s for (* : *) statement.
2317    */
2318   CXCursor_CXXForRangeStmt = 225,
2319 
2320   /** Windows Structured Exception Handling's try statement.
2321    */
2322   CXCursor_SEHTryStmt = 226,
2323 
2324   /** Windows Structured Exception Handling's except statement.
2325    */
2326   CXCursor_SEHExceptStmt = 227,
2327 
2328   /** Windows Structured Exception Handling's finally statement.
2329    */
2330   CXCursor_SEHFinallyStmt = 228,
2331 
2332   /** A MS inline assembly statement extension.
2333    */
2334   CXCursor_MSAsmStmt = 229,
2335 
2336   /** The null statement ";": C99 6.8.3p3.
2337    *
2338    * This cursor kind is used to describe the null statement.
2339    */
2340   CXCursor_NullStmt = 230,
2341 
2342   /** Adaptor class for mixing declarations with statements and
2343    * expressions.
2344    */
2345   CXCursor_DeclStmt = 231,
2346 
2347   /** OpenMP parallel directive.
2348    */
2349   CXCursor_OMPParallelDirective = 232,
2350 
2351   /** OpenMP SIMD directive.
2352    */
2353   CXCursor_OMPSimdDirective = 233,
2354 
2355   /** OpenMP for directive.
2356    */
2357   CXCursor_OMPForDirective = 234,
2358 
2359   /** OpenMP sections directive.
2360    */
2361   CXCursor_OMPSectionsDirective = 235,
2362 
2363   /** OpenMP section directive.
2364    */
2365   CXCursor_OMPSectionDirective = 236,
2366 
2367   /** OpenMP single directive.
2368    */
2369   CXCursor_OMPSingleDirective = 237,
2370 
2371   /** OpenMP parallel for directive.
2372    */
2373   CXCursor_OMPParallelForDirective = 238,
2374 
2375   /** OpenMP parallel sections directive.
2376    */
2377   CXCursor_OMPParallelSectionsDirective = 239,
2378 
2379   /** OpenMP task directive.
2380    */
2381   CXCursor_OMPTaskDirective = 240,
2382 
2383   /** OpenMP master directive.
2384    */
2385   CXCursor_OMPMasterDirective = 241,
2386 
2387   /** OpenMP critical directive.
2388    */
2389   CXCursor_OMPCriticalDirective = 242,
2390 
2391   /** OpenMP taskyield directive.
2392    */
2393   CXCursor_OMPTaskyieldDirective = 243,
2394 
2395   /** OpenMP barrier directive.
2396    */
2397   CXCursor_OMPBarrierDirective = 244,
2398 
2399   /** OpenMP taskwait directive.
2400    */
2401   CXCursor_OMPTaskwaitDirective = 245,
2402 
2403   /** OpenMP flush directive.
2404    */
2405   CXCursor_OMPFlushDirective = 246,
2406 
2407   /** Windows Structured Exception Handling's leave statement.
2408    */
2409   CXCursor_SEHLeaveStmt = 247,
2410 
2411   /** OpenMP ordered directive.
2412    */
2413   CXCursor_OMPOrderedDirective = 248,
2414 
2415   /** OpenMP atomic directive.
2416    */
2417   CXCursor_OMPAtomicDirective = 249,
2418 
2419   /** OpenMP for SIMD directive.
2420    */
2421   CXCursor_OMPForSimdDirective = 250,
2422 
2423   /** OpenMP parallel for SIMD directive.
2424    */
2425   CXCursor_OMPParallelForSimdDirective = 251,
2426 
2427   /** OpenMP target directive.
2428    */
2429   CXCursor_OMPTargetDirective = 252,
2430 
2431   /** OpenMP teams directive.
2432    */
2433   CXCursor_OMPTeamsDirective = 253,
2434 
2435   /** OpenMP taskgroup directive.
2436    */
2437   CXCursor_OMPTaskgroupDirective = 254,
2438 
2439   /** OpenMP cancellation point directive.
2440    */
2441   CXCursor_OMPCancellationPointDirective = 255,
2442 
2443   /** OpenMP cancel directive.
2444    */
2445   CXCursor_OMPCancelDirective = 256,
2446 
2447   /** OpenMP target data directive.
2448    */
2449   CXCursor_OMPTargetDataDirective = 257,
2450 
2451   /** OpenMP taskloop directive.
2452    */
2453   CXCursor_OMPTaskLoopDirective = 258,
2454 
2455   /** OpenMP taskloop simd directive.
2456    */
2457   CXCursor_OMPTaskLoopSimdDirective = 259,
2458 
2459   /** OpenMP distribute directive.
2460    */
2461   CXCursor_OMPDistributeDirective = 260,
2462 
2463   /** OpenMP target enter data directive.
2464    */
2465   CXCursor_OMPTargetEnterDataDirective = 261,
2466 
2467   /** OpenMP target exit data directive.
2468    */
2469   CXCursor_OMPTargetExitDataDirective = 262,
2470 
2471   /** OpenMP target parallel directive.
2472    */
2473   CXCursor_OMPTargetParallelDirective = 263,
2474 
2475   /** OpenMP target parallel for directive.
2476    */
2477   CXCursor_OMPTargetParallelForDirective = 264,
2478 
2479   /** OpenMP target update directive.
2480    */
2481   CXCursor_OMPTargetUpdateDirective = 265,
2482 
2483   /** OpenMP distribute parallel for directive.
2484    */
2485   CXCursor_OMPDistributeParallelForDirective = 266,
2486 
2487   /** OpenMP distribute parallel for simd directive.
2488    */
2489   CXCursor_OMPDistributeParallelForSimdDirective = 267,
2490 
2491   /** OpenMP distribute simd directive.
2492    */
2493   CXCursor_OMPDistributeSimdDirective = 268,
2494 
2495   /** OpenMP target parallel for simd directive.
2496    */
2497   CXCursor_OMPTargetParallelForSimdDirective = 269,
2498 
2499   /** OpenMP target simd directive.
2500    */
2501   CXCursor_OMPTargetSimdDirective = 270,
2502 
2503   /** OpenMP teams distribute directive.
2504    */
2505   CXCursor_OMPTeamsDistributeDirective = 271,
2506 
2507   /** OpenMP teams distribute simd directive.
2508    */
2509   CXCursor_OMPTeamsDistributeSimdDirective = 272,
2510 
2511   /** OpenMP teams distribute parallel for simd directive.
2512    */
2513   CXCursor_OMPTeamsDistributeParallelForSimdDirective = 273,
2514 
2515   /** OpenMP teams distribute parallel for directive.
2516    */
2517   CXCursor_OMPTeamsDistributeParallelForDirective = 274,
2518 
2519   /** OpenMP target teams directive.
2520    */
2521   CXCursor_OMPTargetTeamsDirective = 275,
2522 
2523   /** OpenMP target teams distribute directive.
2524    */
2525   CXCursor_OMPTargetTeamsDistributeDirective = 276,
2526 
2527   /** OpenMP target teams distribute parallel for directive.
2528    */
2529   CXCursor_OMPTargetTeamsDistributeParallelForDirective = 277,
2530 
2531   /** OpenMP target teams distribute parallel for simd directive.
2532    */
2533   CXCursor_OMPTargetTeamsDistributeParallelForSimdDirective = 278,
2534 
2535   /** OpenMP target teams distribute simd directive.
2536    */
2537   CXCursor_OMPTargetTeamsDistributeSimdDirective = 279,
2538 
2539   /** C++2a std::bit_cast expression.
2540    */
2541   CXCursor_BuiltinBitCastExpr = 280,
2542 
2543   /** OpenMP master taskloop directive.
2544    */
2545   CXCursor_OMPMasterTaskLoopDirective = 281,
2546 
2547   /** OpenMP parallel master taskloop directive.
2548    */
2549   CXCursor_OMPParallelMasterTaskLoopDirective = 282,
2550 
2551   /** OpenMP master taskloop simd directive.
2552    */
2553   CXCursor_OMPMasterTaskLoopSimdDirective = 283,
2554 
2555   /** OpenMP parallel master taskloop simd directive.
2556    */
2557   CXCursor_OMPParallelMasterTaskLoopSimdDirective = 284,
2558 
2559   /** OpenMP parallel master directive.
2560    */
2561   CXCursor_OMPParallelMasterDirective = 285,
2562 
2563   /** OpenMP depobj directive.
2564    */
2565   CXCursor_OMPDepobjDirective = 286,
2566 
2567   /** OpenMP scan directive.
2568    */
2569   CXCursor_OMPScanDirective = 287,
2570 
2571   /** OpenMP tile directive.
2572    */
2573   CXCursor_OMPTileDirective = 288,
2574 
2575   /** OpenMP canonical loop.
2576    */
2577   CXCursor_OMPCanonicalLoop = 289,
2578 
2579   /** OpenMP interop directive.
2580    */
2581   CXCursor_OMPInteropDirective = 290,
2582 
2583   /** OpenMP dispatch directive.
2584    */
2585   CXCursor_OMPDispatchDirective = 291,
2586 
2587   /** OpenMP masked directive.
2588    */
2589   CXCursor_OMPMaskedDirective = 292,
2590 
2591   /** OpenMP unroll directive.
2592    */
2593   CXCursor_OMPUnrollDirective = 293,
2594 
2595   /** OpenMP metadirective directive.
2596    */
2597   CXCursor_OMPMetaDirective = 294,
2598 
2599   /** OpenMP loop directive.
2600    */
2601   CXCursor_OMPGenericLoopDirective = 295,
2602 
2603   CXCursor_LastStmt = CXCursor_OMPGenericLoopDirective,
2604 
2605   /**
2606    * Cursor that represents the translation unit itself.
2607    *
2608    * The translation unit cursor exists primarily to act as the root
2609    * cursor for traversing the contents of a translation unit.
2610    */
2611   CXCursor_TranslationUnit = 300,
2612 
2613   /* Attributes */
2614   CXCursor_FirstAttr = 400,
2615   /**
2616    * An attribute whose specific kind is not exposed via this
2617    * interface.
2618    */
2619   CXCursor_UnexposedAttr = 400,
2620 
2621   CXCursor_IBActionAttr = 401,
2622   CXCursor_IBOutletAttr = 402,
2623   CXCursor_IBOutletCollectionAttr = 403,
2624   CXCursor_CXXFinalAttr = 404,
2625   CXCursor_CXXOverrideAttr = 405,
2626   CXCursor_AnnotateAttr = 406,
2627   CXCursor_AsmLabelAttr = 407,
2628   CXCursor_PackedAttr = 408,
2629   CXCursor_PureAttr = 409,
2630   CXCursor_ConstAttr = 410,
2631   CXCursor_NoDuplicateAttr = 411,
2632   CXCursor_CUDAConstantAttr = 412,
2633   CXCursor_CUDADeviceAttr = 413,
2634   CXCursor_CUDAGlobalAttr = 414,
2635   CXCursor_CUDAHostAttr = 415,
2636   CXCursor_CUDASharedAttr = 416,
2637   CXCursor_VisibilityAttr = 417,
2638   CXCursor_DLLExport = 418,
2639   CXCursor_DLLImport = 419,
2640   CXCursor_NSReturnsRetained = 420,
2641   CXCursor_NSReturnsNotRetained = 421,
2642   CXCursor_NSReturnsAutoreleased = 422,
2643   CXCursor_NSConsumesSelf = 423,
2644   CXCursor_NSConsumed = 424,
2645   CXCursor_ObjCException = 425,
2646   CXCursor_ObjCNSObject = 426,
2647   CXCursor_ObjCIndependentClass = 427,
2648   CXCursor_ObjCPreciseLifetime = 428,
2649   CXCursor_ObjCReturnsInnerPointer = 429,
2650   CXCursor_ObjCRequiresSuper = 430,
2651   CXCursor_ObjCRootClass = 431,
2652   CXCursor_ObjCSubclassingRestricted = 432,
2653   CXCursor_ObjCExplicitProtocolImpl = 433,
2654   CXCursor_ObjCDesignatedInitializer = 434,
2655   CXCursor_ObjCRuntimeVisible = 435,
2656   CXCursor_ObjCBoxable = 436,
2657   CXCursor_FlagEnum = 437,
2658   CXCursor_ConvergentAttr = 438,
2659   CXCursor_WarnUnusedAttr = 439,
2660   CXCursor_WarnUnusedResultAttr = 440,
2661   CXCursor_AlignedAttr = 441,
2662   CXCursor_LastAttr = CXCursor_AlignedAttr,
2663 
2664   /* Preprocessing */
2665   CXCursor_PreprocessingDirective = 500,
2666   CXCursor_MacroDefinition = 501,
2667   CXCursor_MacroExpansion = 502,
2668   CXCursor_MacroInstantiation = CXCursor_MacroExpansion,
2669   CXCursor_InclusionDirective = 503,
2670   CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective,
2671   CXCursor_LastPreprocessing = CXCursor_InclusionDirective,
2672 
2673   /* Extra Declarations */
2674   /**
2675    * A module import declaration.
2676    */
2677   CXCursor_ModuleImportDecl = 600,
2678   CXCursor_TypeAliasTemplateDecl = 601,
2679   /**
2680    * A static_assert or _Static_assert node
2681    */
2682   CXCursor_StaticAssert = 602,
2683   /**
2684    * a friend declaration.
2685    */
2686   CXCursor_FriendDecl = 603,
2687   CXCursor_FirstExtraDecl = CXCursor_ModuleImportDecl,
2688   CXCursor_LastExtraDecl = CXCursor_FriendDecl,
2689 
2690   /**
2691    * A code completion overload candidate.
2692    */
2693   CXCursor_OverloadCandidate = 700
2694 };
2695 
2696 /**
2697  * A cursor representing some element in the abstract syntax tree for
2698  * a translation unit.
2699  *
2700  * The cursor abstraction unifies the different kinds of entities in a
2701  * program--declaration, statements, expressions, references to declarations,
2702  * etc.--under a single "cursor" abstraction with a common set of operations.
2703  * Common operation for a cursor include: getting the physical location in
2704  * a source file where the cursor points, getting the name associated with a
2705  * cursor, and retrieving cursors for any child nodes of a particular cursor.
2706  *
2707  * Cursors can be produced in two specific ways.
2708  * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
2709  * from which one can use clang_visitChildren() to explore the rest of the
2710  * translation unit. clang_getCursor() maps from a physical source location
2711  * to the entity that resides at that location, allowing one to map from the
2712  * source code into the AST.
2713  */
2714 typedef struct {
2715   enum CXCursorKind kind;
2716   int xdata;
2717   const void *data[3];
2718 } CXCursor;
2719 
2720 /**
2721  * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
2722  *
2723  * @{
2724  */
2725 
2726 /**
2727  * Retrieve the NULL cursor, which represents no entity.
2728  */
2729 CINDEX_LINKAGE CXCursor clang_getNullCursor(void);
2730 
2731 /**
2732  * Retrieve the cursor that represents the given translation unit.
2733  *
2734  * The translation unit cursor can be used to start traversing the
2735  * various declarations within the given translation unit.
2736  */
2737 CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit);
2738 
2739 /**
2740  * Determine whether two cursors are equivalent.
2741  */
2742 CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor);
2743 
2744 /**
2745  * Returns non-zero if \p cursor is null.
2746  */
2747 CINDEX_LINKAGE int clang_Cursor_isNull(CXCursor cursor);
2748 
2749 /**
2750  * Compute a hash value for the given cursor.
2751  */
2752 CINDEX_LINKAGE unsigned clang_hashCursor(CXCursor);
2753 
2754 /**
2755  * Retrieve the kind of the given cursor.
2756  */
2757 CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor);
2758 
2759 /**
2760  * Determine whether the given cursor kind represents a declaration.
2761  */
2762 CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind);
2763 
2764 /**
2765  * Determine whether the given declaration is invalid.
2766  *
2767  * A declaration is invalid if it could not be parsed successfully.
2768  *
2769  * \returns non-zero if the cursor represents a declaration and it is
2770  * invalid, otherwise NULL.
2771  */
2772 CINDEX_LINKAGE unsigned clang_isInvalidDeclaration(CXCursor);
2773 
2774 /**
2775  * Determine whether the given cursor kind represents a simple
2776  * reference.
2777  *
2778  * Note that other kinds of cursors (such as expressions) can also refer to
2779  * other cursors. Use clang_getCursorReferenced() to determine whether a
2780  * particular cursor refers to another entity.
2781  */
2782 CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind);
2783 
2784 /**
2785  * Determine whether the given cursor kind represents an expression.
2786  */
2787 CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind);
2788 
2789 /**
2790  * Determine whether the given cursor kind represents a statement.
2791  */
2792 CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind);
2793 
2794 /**
2795  * Determine whether the given cursor kind represents an attribute.
2796  */
2797 CINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind);
2798 
2799 /**
2800  * Determine whether the given cursor has any attributes.
2801  */
2802 CINDEX_LINKAGE unsigned clang_Cursor_hasAttrs(CXCursor C);
2803 
2804 /**
2805  * Determine whether the given cursor kind represents an invalid
2806  * cursor.
2807  */
2808 CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind);
2809 
2810 /**
2811  * Determine whether the given cursor kind represents a translation
2812  * unit.
2813  */
2814 CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind);
2815 
2816 /***
2817  * Determine whether the given cursor represents a preprocessing
2818  * element, such as a preprocessor directive or macro instantiation.
2819  */
2820 CINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind);
2821 
2822 /***
2823  * Determine whether the given cursor represents a currently
2824  *  unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
2825  */
2826 CINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind);
2827 
2828 /**
2829  * Describe the linkage of the entity referred to by a cursor.
2830  */
2831 enum CXLinkageKind {
2832   /** This value indicates that no linkage information is available
2833    * for a provided CXCursor. */
2834   CXLinkage_Invalid,
2835   /**
2836    * This is the linkage for variables, parameters, and so on that
2837    *  have automatic storage.  This covers normal (non-extern) local variables.
2838    */
2839   CXLinkage_NoLinkage,
2840   /** This is the linkage for static variables and static functions. */
2841   CXLinkage_Internal,
2842   /** This is the linkage for entities with external linkage that live
2843    * in C++ anonymous namespaces.*/
2844   CXLinkage_UniqueExternal,
2845   /** This is the linkage for entities with true, external linkage. */
2846   CXLinkage_External
2847 };
2848 
2849 /**
2850  * Determine the linkage of the entity referred to by a given cursor.
2851  */
2852 CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor);
2853 
2854 enum CXVisibilityKind {
2855   /** This value indicates that no visibility information is available
2856    * for a provided CXCursor. */
2857   CXVisibility_Invalid,
2858 
2859   /** Symbol not seen by the linker. */
2860   CXVisibility_Hidden,
2861   /** Symbol seen by the linker but resolves to a symbol inside this object. */
2862   CXVisibility_Protected,
2863   /** Symbol seen by the linker and acts like a normal symbol. */
2864   CXVisibility_Default
2865 };
2866 
2867 /**
2868  * Describe the visibility of the entity referred to by a cursor.
2869  *
2870  * This returns the default visibility if not explicitly specified by
2871  * a visibility attribute. The default visibility may be changed by
2872  * commandline arguments.
2873  *
2874  * \param cursor The cursor to query.
2875  *
2876  * \returns The visibility of the cursor.
2877  */
2878 CINDEX_LINKAGE enum CXVisibilityKind clang_getCursorVisibility(CXCursor cursor);
2879 
2880 /**
2881  * Determine the availability of the entity that this cursor refers to,
2882  * taking the current target platform into account.
2883  *
2884  * \param cursor The cursor to query.
2885  *
2886  * \returns The availability of the cursor.
2887  */
2888 CINDEX_LINKAGE enum CXAvailabilityKind
2889 clang_getCursorAvailability(CXCursor cursor);
2890 
2891 /**
2892  * Describes the availability of a given entity on a particular platform, e.g.,
2893  * a particular class might only be available on Mac OS 10.7 or newer.
2894  */
2895 typedef struct CXPlatformAvailability {
2896   /**
2897    * A string that describes the platform for which this structure
2898    * provides availability information.
2899    *
2900    * Possible values are "ios" or "macos".
2901    */
2902   CXString Platform;
2903   /**
2904    * The version number in which this entity was introduced.
2905    */
2906   CXVersion Introduced;
2907   /**
2908    * The version number in which this entity was deprecated (but is
2909    * still available).
2910    */
2911   CXVersion Deprecated;
2912   /**
2913    * The version number in which this entity was obsoleted, and therefore
2914    * is no longer available.
2915    */
2916   CXVersion Obsoleted;
2917   /**
2918    * Whether the entity is unconditionally unavailable on this platform.
2919    */
2920   int Unavailable;
2921   /**
2922    * An optional message to provide to a user of this API, e.g., to
2923    * suggest replacement APIs.
2924    */
2925   CXString Message;
2926 } CXPlatformAvailability;
2927 
2928 /**
2929  * Determine the availability of the entity that this cursor refers to
2930  * on any platforms for which availability information is known.
2931  *
2932  * \param cursor The cursor to query.
2933  *
2934  * \param always_deprecated If non-NULL, will be set to indicate whether the
2935  * entity is deprecated on all platforms.
2936  *
2937  * \param deprecated_message If non-NULL, will be set to the message text
2938  * provided along with the unconditional deprecation of this entity. The client
2939  * is responsible for deallocating this string.
2940  *
2941  * \param always_unavailable If non-NULL, will be set to indicate whether the
2942  * entity is unavailable on all platforms.
2943  *
2944  * \param unavailable_message If non-NULL, will be set to the message text
2945  * provided along with the unconditional unavailability of this entity. The
2946  * client is responsible for deallocating this string.
2947  *
2948  * \param availability If non-NULL, an array of CXPlatformAvailability instances
2949  * that will be populated with platform availability information, up to either
2950  * the number of platforms for which availability information is available (as
2951  * returned by this function) or \c availability_size, whichever is smaller.
2952  *
2953  * \param availability_size The number of elements available in the
2954  * \c availability array.
2955  *
2956  * \returns The number of platforms (N) for which availability information is
2957  * available (which is unrelated to \c availability_size).
2958  *
2959  * Note that the client is responsible for calling
2960  * \c clang_disposeCXPlatformAvailability to free each of the
2961  * platform-availability structures returned. There are
2962  * \c min(N, availability_size) such structures.
2963  */
2964 CINDEX_LINKAGE int clang_getCursorPlatformAvailability(
2965     CXCursor cursor, int *always_deprecated, CXString *deprecated_message,
2966     int *always_unavailable, CXString *unavailable_message,
2967     CXPlatformAvailability *availability, int availability_size);
2968 
2969 /**
2970  * Free the memory associated with a \c CXPlatformAvailability structure.
2971  */
2972 CINDEX_LINKAGE void
2973 clang_disposeCXPlatformAvailability(CXPlatformAvailability *availability);
2974 
2975 /**
2976  * If cursor refers to a variable declaration and it has initializer returns
2977  * cursor referring to the initializer otherwise return null cursor.
2978  */
2979 CINDEX_LINKAGE CXCursor clang_Cursor_getVarDeclInitializer(CXCursor cursor);
2980 
2981 /**
2982  * If cursor refers to a variable declaration that has global storage returns 1.
2983  * If cursor refers to a variable declaration that doesn't have global storage
2984  * returns 0. Otherwise returns -1.
2985  */
2986 CINDEX_LINKAGE int clang_Cursor_hasVarDeclGlobalStorage(CXCursor cursor);
2987 
2988 /**
2989  * If cursor refers to a variable declaration that has external storage
2990  * returns 1. If cursor refers to a variable declaration that doesn't have
2991  * external storage returns 0. Otherwise returns -1.
2992  */
2993 CINDEX_LINKAGE int clang_Cursor_hasVarDeclExternalStorage(CXCursor cursor);
2994 
2995 /**
2996  * Describe the "language" of the entity referred to by a cursor.
2997  */
2998 enum CXLanguageKind {
2999   CXLanguage_Invalid = 0,
3000   CXLanguage_C,
3001   CXLanguage_ObjC,
3002   CXLanguage_CPlusPlus
3003 };
3004 
3005 /**
3006  * Determine the "language" of the entity referred to by a given cursor.
3007  */
3008 CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor);
3009 
3010 /**
3011  * Describe the "thread-local storage (TLS) kind" of the declaration
3012  * referred to by a cursor.
3013  */
3014 enum CXTLSKind { CXTLS_None = 0, CXTLS_Dynamic, CXTLS_Static };
3015 
3016 /**
3017  * Determine the "thread-local storage (TLS) kind" of the declaration
3018  * referred to by a cursor.
3019  */
3020 CINDEX_LINKAGE enum CXTLSKind clang_getCursorTLSKind(CXCursor cursor);
3021 
3022 /**
3023  * Returns the translation unit that a cursor originated from.
3024  */
3025 CINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor);
3026 
3027 /**
3028  * A fast container representing a set of CXCursors.
3029  */
3030 typedef struct CXCursorSetImpl *CXCursorSet;
3031 
3032 /**
3033  * Creates an empty CXCursorSet.
3034  */
3035 CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void);
3036 
3037 /**
3038  * Disposes a CXCursorSet and releases its associated memory.
3039  */
3040 CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset);
3041 
3042 /**
3043  * Queries a CXCursorSet to see if it contains a specific CXCursor.
3044  *
3045  * \returns non-zero if the set contains the specified cursor.
3046  */
3047 CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset,
3048                                                    CXCursor cursor);
3049 
3050 /**
3051  * Inserts a CXCursor into a CXCursorSet.
3052  *
3053  * \returns zero if the CXCursor was already in the set, and non-zero otherwise.
3054  */
3055 CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset,
3056                                                  CXCursor cursor);
3057 
3058 /**
3059  * Determine the semantic parent of the given cursor.
3060  *
3061  * The semantic parent of a cursor is the cursor that semantically contains
3062  * the given \p cursor. For many declarations, the lexical and semantic parents
3063  * are equivalent (the lexical parent is returned by
3064  * \c clang_getCursorLexicalParent()). They diverge when declarations or
3065  * definitions are provided out-of-line. For example:
3066  *
3067  * \code
3068  * class C {
3069  *  void f();
3070  * };
3071  *
3072  * void C::f() { }
3073  * \endcode
3074  *
3075  * In the out-of-line definition of \c C::f, the semantic parent is
3076  * the class \c C, of which this function is a member. The lexical parent is
3077  * the place where the declaration actually occurs in the source code; in this
3078  * case, the definition occurs in the translation unit. In general, the
3079  * lexical parent for a given entity can change without affecting the semantics
3080  * of the program, and the lexical parent of different declarations of the
3081  * same entity may be different. Changing the semantic parent of a declaration,
3082  * on the other hand, can have a major impact on semantics, and redeclarations
3083  * of a particular entity should all have the same semantic context.
3084  *
3085  * In the example above, both declarations of \c C::f have \c C as their
3086  * semantic context, while the lexical context of the first \c C::f is \c C
3087  * and the lexical context of the second \c C::f is the translation unit.
3088  *
3089  * For global declarations, the semantic parent is the translation unit.
3090  */
3091 CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor);
3092 
3093 /**
3094  * Determine the lexical parent of the given cursor.
3095  *
3096  * The lexical parent of a cursor is the cursor in which the given \p cursor
3097  * was actually written. For many declarations, the lexical and semantic parents
3098  * are equivalent (the semantic parent is returned by
3099  * \c clang_getCursorSemanticParent()). They diverge when declarations or
3100  * definitions are provided out-of-line. For example:
3101  *
3102  * \code
3103  * class C {
3104  *  void f();
3105  * };
3106  *
3107  * void C::f() { }
3108  * \endcode
3109  *
3110  * In the out-of-line definition of \c C::f, the semantic parent is
3111  * the class \c C, of which this function is a member. The lexical parent is
3112  * the place where the declaration actually occurs in the source code; in this
3113  * case, the definition occurs in the translation unit. In general, the
3114  * lexical parent for a given entity can change without affecting the semantics
3115  * of the program, and the lexical parent of different declarations of the
3116  * same entity may be different. Changing the semantic parent of a declaration,
3117  * on the other hand, can have a major impact on semantics, and redeclarations
3118  * of a particular entity should all have the same semantic context.
3119  *
3120  * In the example above, both declarations of \c C::f have \c C as their
3121  * semantic context, while the lexical context of the first \c C::f is \c C
3122  * and the lexical context of the second \c C::f is the translation unit.
3123  *
3124  * For declarations written in the global scope, the lexical parent is
3125  * the translation unit.
3126  */
3127 CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor);
3128 
3129 /**
3130  * Determine the set of methods that are overridden by the given
3131  * method.
3132  *
3133  * In both Objective-C and C++, a method (aka virtual member function,
3134  * in C++) can override a virtual method in a base class. For
3135  * Objective-C, a method is said to override any method in the class's
3136  * base class, its protocols, or its categories' protocols, that has the same
3137  * selector and is of the same kind (class or instance).
3138  * If no such method exists, the search continues to the class's superclass,
3139  * its protocols, and its categories, and so on. A method from an Objective-C
3140  * implementation is considered to override the same methods as its
3141  * corresponding method in the interface.
3142  *
3143  * For C++, a virtual member function overrides any virtual member
3144  * function with the same signature that occurs in its base
3145  * classes. With multiple inheritance, a virtual member function can
3146  * override several virtual member functions coming from different
3147  * base classes.
3148  *
3149  * In all cases, this function determines the immediate overridden
3150  * method, rather than all of the overridden methods. For example, if
3151  * a method is originally declared in a class A, then overridden in B
3152  * (which in inherits from A) and also in C (which inherited from B),
3153  * then the only overridden method returned from this function when
3154  * invoked on C's method will be B's method. The client may then
3155  * invoke this function again, given the previously-found overridden
3156  * methods, to map out the complete method-override set.
3157  *
3158  * \param cursor A cursor representing an Objective-C or C++
3159  * method. This routine will compute the set of methods that this
3160  * method overrides.
3161  *
3162  * \param overridden A pointer whose pointee will be replaced with a
3163  * pointer to an array of cursors, representing the set of overridden
3164  * methods. If there are no overridden methods, the pointee will be
3165  * set to NULL. The pointee must be freed via a call to
3166  * \c clang_disposeOverriddenCursors().
3167  *
3168  * \param num_overridden A pointer to the number of overridden
3169  * functions, will be set to the number of overridden functions in the
3170  * array pointed to by \p overridden.
3171  */
3172 CINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor,
3173                                                CXCursor **overridden,
3174                                                unsigned *num_overridden);
3175 
3176 /**
3177  * Free the set of overridden cursors returned by \c
3178  * clang_getOverriddenCursors().
3179  */
3180 CINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden);
3181 
3182 /**
3183  * Retrieve the file that is included by the given inclusion directive
3184  * cursor.
3185  */
3186 CINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor);
3187 
3188 /**
3189  * @}
3190  */
3191 
3192 /**
3193  * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
3194  *
3195  * Cursors represent a location within the Abstract Syntax Tree (AST). These
3196  * routines help map between cursors and the physical locations where the
3197  * described entities occur in the source code. The mapping is provided in
3198  * both directions, so one can map from source code to the AST and back.
3199  *
3200  * @{
3201  */
3202 
3203 /**
3204  * Map a source location to the cursor that describes the entity at that
3205  * location in the source code.
3206  *
3207  * clang_getCursor() maps an arbitrary source location within a translation
3208  * unit down to the most specific cursor that describes the entity at that
3209  * location. For example, given an expression \c x + y, invoking
3210  * clang_getCursor() with a source location pointing to "x" will return the
3211  * cursor for "x"; similarly for "y". If the cursor points anywhere between
3212  * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
3213  * will return a cursor referring to the "+" expression.
3214  *
3215  * \returns a cursor representing the entity at the given source location, or
3216  * a NULL cursor if no such entity can be found.
3217  */
3218 CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation);
3219 
3220 /**
3221  * Retrieve the physical location of the source constructor referenced
3222  * by the given cursor.
3223  *
3224  * The location of a declaration is typically the location of the name of that
3225  * declaration, where the name of that declaration would occur if it is
3226  * unnamed, or some keyword that introduces that particular declaration.
3227  * The location of a reference is where that reference occurs within the
3228  * source code.
3229  */
3230 CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor);
3231 
3232 /**
3233  * Retrieve the physical extent of the source construct referenced by
3234  * the given cursor.
3235  *
3236  * The extent of a cursor starts with the file/line/column pointing at the
3237  * first character within the source construct that the cursor refers to and
3238  * ends with the last character within that source construct. For a
3239  * declaration, the extent covers the declaration itself. For a reference,
3240  * the extent covers the location of the reference (e.g., where the referenced
3241  * entity was actually used).
3242  */
3243 CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor);
3244 
3245 /**
3246  * @}
3247  */
3248 
3249 /**
3250  * \defgroup CINDEX_TYPES Type information for CXCursors
3251  *
3252  * @{
3253  */
3254 
3255 /**
3256  * Describes the kind of type
3257  */
3258 enum CXTypeKind {
3259   /**
3260    * Represents an invalid type (e.g., where no type is available).
3261    */
3262   CXType_Invalid = 0,
3263 
3264   /**
3265    * A type whose specific kind is not exposed via this
3266    * interface.
3267    */
3268   CXType_Unexposed = 1,
3269 
3270   /* Builtin types */
3271   CXType_Void = 2,
3272   CXType_Bool = 3,
3273   CXType_Char_U = 4,
3274   CXType_UChar = 5,
3275   CXType_Char16 = 6,
3276   CXType_Char32 = 7,
3277   CXType_UShort = 8,
3278   CXType_UInt = 9,
3279   CXType_ULong = 10,
3280   CXType_ULongLong = 11,
3281   CXType_UInt128 = 12,
3282   CXType_Char_S = 13,
3283   CXType_SChar = 14,
3284   CXType_WChar = 15,
3285   CXType_Short = 16,
3286   CXType_Int = 17,
3287   CXType_Long = 18,
3288   CXType_LongLong = 19,
3289   CXType_Int128 = 20,
3290   CXType_Float = 21,
3291   CXType_Double = 22,
3292   CXType_LongDouble = 23,
3293   CXType_NullPtr = 24,
3294   CXType_Overload = 25,
3295   CXType_Dependent = 26,
3296   CXType_ObjCId = 27,
3297   CXType_ObjCClass = 28,
3298   CXType_ObjCSel = 29,
3299   CXType_Float128 = 30,
3300   CXType_Half = 31,
3301   CXType_Float16 = 32,
3302   CXType_ShortAccum = 33,
3303   CXType_Accum = 34,
3304   CXType_LongAccum = 35,
3305   CXType_UShortAccum = 36,
3306   CXType_UAccum = 37,
3307   CXType_ULongAccum = 38,
3308   CXType_BFloat16 = 39,
3309   CXType_Ibm128 = 40,
3310   CXType_FirstBuiltin = CXType_Void,
3311   CXType_LastBuiltin = CXType_Ibm128,
3312 
3313   CXType_Complex = 100,
3314   CXType_Pointer = 101,
3315   CXType_BlockPointer = 102,
3316   CXType_LValueReference = 103,
3317   CXType_RValueReference = 104,
3318   CXType_Record = 105,
3319   CXType_Enum = 106,
3320   CXType_Typedef = 107,
3321   CXType_ObjCInterface = 108,
3322   CXType_ObjCObjectPointer = 109,
3323   CXType_FunctionNoProto = 110,
3324   CXType_FunctionProto = 111,
3325   CXType_ConstantArray = 112,
3326   CXType_Vector = 113,
3327   CXType_IncompleteArray = 114,
3328   CXType_VariableArray = 115,
3329   CXType_DependentSizedArray = 116,
3330   CXType_MemberPointer = 117,
3331   CXType_Auto = 118,
3332 
3333   /**
3334    * Represents a type that was referred to using an elaborated type keyword.
3335    *
3336    * E.g., struct S, or via a qualified name, e.g., N::M::type, or both.
3337    */
3338   CXType_Elaborated = 119,
3339 
3340   /* OpenCL PipeType. */
3341   CXType_Pipe = 120,
3342 
3343   /* OpenCL builtin types. */
3344   CXType_OCLImage1dRO = 121,
3345   CXType_OCLImage1dArrayRO = 122,
3346   CXType_OCLImage1dBufferRO = 123,
3347   CXType_OCLImage2dRO = 124,
3348   CXType_OCLImage2dArrayRO = 125,
3349   CXType_OCLImage2dDepthRO = 126,
3350   CXType_OCLImage2dArrayDepthRO = 127,
3351   CXType_OCLImage2dMSAARO = 128,
3352   CXType_OCLImage2dArrayMSAARO = 129,
3353   CXType_OCLImage2dMSAADepthRO = 130,
3354   CXType_OCLImage2dArrayMSAADepthRO = 131,
3355   CXType_OCLImage3dRO = 132,
3356   CXType_OCLImage1dWO = 133,
3357   CXType_OCLImage1dArrayWO = 134,
3358   CXType_OCLImage1dBufferWO = 135,
3359   CXType_OCLImage2dWO = 136,
3360   CXType_OCLImage2dArrayWO = 137,
3361   CXType_OCLImage2dDepthWO = 138,
3362   CXType_OCLImage2dArrayDepthWO = 139,
3363   CXType_OCLImage2dMSAAWO = 140,
3364   CXType_OCLImage2dArrayMSAAWO = 141,
3365   CXType_OCLImage2dMSAADepthWO = 142,
3366   CXType_OCLImage2dArrayMSAADepthWO = 143,
3367   CXType_OCLImage3dWO = 144,
3368   CXType_OCLImage1dRW = 145,
3369   CXType_OCLImage1dArrayRW = 146,
3370   CXType_OCLImage1dBufferRW = 147,
3371   CXType_OCLImage2dRW = 148,
3372   CXType_OCLImage2dArrayRW = 149,
3373   CXType_OCLImage2dDepthRW = 150,
3374   CXType_OCLImage2dArrayDepthRW = 151,
3375   CXType_OCLImage2dMSAARW = 152,
3376   CXType_OCLImage2dArrayMSAARW = 153,
3377   CXType_OCLImage2dMSAADepthRW = 154,
3378   CXType_OCLImage2dArrayMSAADepthRW = 155,
3379   CXType_OCLImage3dRW = 156,
3380   CXType_OCLSampler = 157,
3381   CXType_OCLEvent = 158,
3382   CXType_OCLQueue = 159,
3383   CXType_OCLReserveID = 160,
3384 
3385   CXType_ObjCObject = 161,
3386   CXType_ObjCTypeParam = 162,
3387   CXType_Attributed = 163,
3388 
3389   CXType_OCLIntelSubgroupAVCMcePayload = 164,
3390   CXType_OCLIntelSubgroupAVCImePayload = 165,
3391   CXType_OCLIntelSubgroupAVCRefPayload = 166,
3392   CXType_OCLIntelSubgroupAVCSicPayload = 167,
3393   CXType_OCLIntelSubgroupAVCMceResult = 168,
3394   CXType_OCLIntelSubgroupAVCImeResult = 169,
3395   CXType_OCLIntelSubgroupAVCRefResult = 170,
3396   CXType_OCLIntelSubgroupAVCSicResult = 171,
3397   CXType_OCLIntelSubgroupAVCImeResultSingleRefStreamout = 172,
3398   CXType_OCLIntelSubgroupAVCImeResultDualRefStreamout = 173,
3399   CXType_OCLIntelSubgroupAVCImeSingleRefStreamin = 174,
3400 
3401   CXType_OCLIntelSubgroupAVCImeDualRefStreamin = 175,
3402 
3403   CXType_ExtVector = 176,
3404   CXType_Atomic = 177
3405 };
3406 
3407 /**
3408  * Describes the calling convention of a function type
3409  */
3410 enum CXCallingConv {
3411   CXCallingConv_Default = 0,
3412   CXCallingConv_C = 1,
3413   CXCallingConv_X86StdCall = 2,
3414   CXCallingConv_X86FastCall = 3,
3415   CXCallingConv_X86ThisCall = 4,
3416   CXCallingConv_X86Pascal = 5,
3417   CXCallingConv_AAPCS = 6,
3418   CXCallingConv_AAPCS_VFP = 7,
3419   CXCallingConv_X86RegCall = 8,
3420   CXCallingConv_IntelOclBicc = 9,
3421   CXCallingConv_Win64 = 10,
3422   /* Alias for compatibility with older versions of API. */
3423   CXCallingConv_X86_64Win64 = CXCallingConv_Win64,
3424   CXCallingConv_X86_64SysV = 11,
3425   CXCallingConv_X86VectorCall = 12,
3426   CXCallingConv_Swift = 13,
3427   CXCallingConv_PreserveMost = 14,
3428   CXCallingConv_PreserveAll = 15,
3429   CXCallingConv_AArch64VectorCall = 16,
3430   CXCallingConv_SwiftAsync = 17,
3431 
3432   CXCallingConv_Invalid = 100,
3433   CXCallingConv_Unexposed = 200
3434 };
3435 
3436 /**
3437  * The type of an element in the abstract syntax tree.
3438  *
3439  */
3440 typedef struct {
3441   enum CXTypeKind kind;
3442   void *data[2];
3443 } CXType;
3444 
3445 /**
3446  * Retrieve the type of a CXCursor (if any).
3447  */
3448 CINDEX_LINKAGE CXType clang_getCursorType(CXCursor C);
3449 
3450 /**
3451  * Pretty-print the underlying type using the rules of the
3452  * language of the translation unit from which it came.
3453  *
3454  * If the type is invalid, an empty string is returned.
3455  */
3456 CINDEX_LINKAGE CXString clang_getTypeSpelling(CXType CT);
3457 
3458 /**
3459  * Retrieve the underlying type of a typedef declaration.
3460  *
3461  * If the cursor does not reference a typedef declaration, an invalid type is
3462  * returned.
3463  */
3464 CINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C);
3465 
3466 /**
3467  * Retrieve the integer type of an enum declaration.
3468  *
3469  * If the cursor does not reference an enum declaration, an invalid type is
3470  * returned.
3471  */
3472 CINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C);
3473 
3474 /**
3475  * Retrieve the integer value of an enum constant declaration as a signed
3476  *  long long.
3477  *
3478  * If the cursor does not reference an enum constant declaration, LLONG_MIN is
3479  * returned. Since this is also potentially a valid constant value, the kind of
3480  * the cursor must be verified before calling this function.
3481  */
3482 CINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C);
3483 
3484 /**
3485  * Retrieve the integer value of an enum constant declaration as an unsigned
3486  *  long long.
3487  *
3488  * If the cursor does not reference an enum constant declaration, ULLONG_MAX is
3489  * returned. Since this is also potentially a valid constant value, the kind of
3490  * the cursor must be verified before calling this function.
3491  */
3492 CINDEX_LINKAGE unsigned long long
3493 clang_getEnumConstantDeclUnsignedValue(CXCursor C);
3494 
3495 /**
3496  * Retrieve the bit width of a bit field declaration as an integer.
3497  *
3498  * If a cursor that is not a bit field declaration is passed in, -1 is returned.
3499  */
3500 CINDEX_LINKAGE int clang_getFieldDeclBitWidth(CXCursor C);
3501 
3502 /**
3503  * Retrieve the number of non-variadic arguments associated with a given
3504  * cursor.
3505  *
3506  * The number of arguments can be determined for calls as well as for
3507  * declarations of functions or methods. For other cursors -1 is returned.
3508  */
3509 CINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C);
3510 
3511 /**
3512  * Retrieve the argument cursor of a function or method.
3513  *
3514  * The argument cursor can be determined for calls as well as for declarations
3515  * of functions or methods. For other cursors and for invalid indices, an
3516  * invalid cursor is returned.
3517  */
3518 CINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i);
3519 
3520 /**
3521  * Describes the kind of a template argument.
3522  *
3523  * See the definition of llvm::clang::TemplateArgument::ArgKind for full
3524  * element descriptions.
3525  */
3526 enum CXTemplateArgumentKind {
3527   CXTemplateArgumentKind_Null,
3528   CXTemplateArgumentKind_Type,
3529   CXTemplateArgumentKind_Declaration,
3530   CXTemplateArgumentKind_NullPtr,
3531   CXTemplateArgumentKind_Integral,
3532   CXTemplateArgumentKind_Template,
3533   CXTemplateArgumentKind_TemplateExpansion,
3534   CXTemplateArgumentKind_Expression,
3535   CXTemplateArgumentKind_Pack,
3536   /* Indicates an error case, preventing the kind from being deduced. */
3537   CXTemplateArgumentKind_Invalid
3538 };
3539 
3540 /**
3541  *Returns the number of template args of a function decl representing a
3542  * template specialization.
3543  *
3544  * If the argument cursor cannot be converted into a template function
3545  * declaration, -1 is returned.
3546  *
3547  * For example, for the following declaration and specialization:
3548  *   template <typename T, int kInt, bool kBool>
3549  *   void foo() { ... }
3550  *
3551  *   template <>
3552  *   void foo<float, -7, true>();
3553  *
3554  * The value 3 would be returned from this call.
3555  */
3556 CINDEX_LINKAGE int clang_Cursor_getNumTemplateArguments(CXCursor C);
3557 
3558 /**
3559  * Retrieve the kind of the I'th template argument of the CXCursor C.
3560  *
3561  * If the argument CXCursor does not represent a FunctionDecl, an invalid
3562  * template argument kind is returned.
3563  *
3564  * For example, for the following declaration and specialization:
3565  *   template <typename T, int kInt, bool kBool>
3566  *   void foo() { ... }
3567  *
3568  *   template <>
3569  *   void foo<float, -7, true>();
3570  *
3571  * For I = 0, 1, and 2, Type, Integral, and Integral will be returned,
3572  * respectively.
3573  */
3574 CINDEX_LINKAGE enum CXTemplateArgumentKind
3575 clang_Cursor_getTemplateArgumentKind(CXCursor C, unsigned I);
3576 
3577 /**
3578  * Retrieve a CXType representing the type of a TemplateArgument of a
3579  *  function decl representing a template specialization.
3580  *
3581  * If the argument CXCursor does not represent a FunctionDecl whose I'th
3582  * template argument has a kind of CXTemplateArgKind_Integral, an invalid type
3583  * is returned.
3584  *
3585  * For example, for the following declaration and specialization:
3586  *   template <typename T, int kInt, bool kBool>
3587  *   void foo() { ... }
3588  *
3589  *   template <>
3590  *   void foo<float, -7, true>();
3591  *
3592  * If called with I = 0, "float", will be returned.
3593  * Invalid types will be returned for I == 1 or 2.
3594  */
3595 CINDEX_LINKAGE CXType clang_Cursor_getTemplateArgumentType(CXCursor C,
3596                                                            unsigned I);
3597 
3598 /**
3599  * Retrieve the value of an Integral TemplateArgument (of a function
3600  *  decl representing a template specialization) as a signed long long.
3601  *
3602  * It is undefined to call this function on a CXCursor that does not represent a
3603  * FunctionDecl or whose I'th template argument is not an integral value.
3604  *
3605  * For example, for the following declaration and specialization:
3606  *   template <typename T, int kInt, bool kBool>
3607  *   void foo() { ... }
3608  *
3609  *   template <>
3610  *   void foo<float, -7, true>();
3611  *
3612  * If called with I = 1 or 2, -7 or true will be returned, respectively.
3613  * For I == 0, this function's behavior is undefined.
3614  */
3615 CINDEX_LINKAGE long long clang_Cursor_getTemplateArgumentValue(CXCursor C,
3616                                                                unsigned I);
3617 
3618 /**
3619  * Retrieve the value of an Integral TemplateArgument (of a function
3620  *  decl representing a template specialization) as an unsigned long long.
3621  *
3622  * It is undefined to call this function on a CXCursor that does not represent a
3623  * FunctionDecl or whose I'th template argument is not an integral value.
3624  *
3625  * For example, for the following declaration and specialization:
3626  *   template <typename T, int kInt, bool kBool>
3627  *   void foo() { ... }
3628  *
3629  *   template <>
3630  *   void foo<float, 2147483649, true>();
3631  *
3632  * If called with I = 1 or 2, 2147483649 or true will be returned, respectively.
3633  * For I == 0, this function's behavior is undefined.
3634  */
3635 CINDEX_LINKAGE unsigned long long
3636 clang_Cursor_getTemplateArgumentUnsignedValue(CXCursor C, unsigned I);
3637 
3638 /**
3639  * Determine whether two CXTypes represent the same type.
3640  *
3641  * \returns non-zero if the CXTypes represent the same type and
3642  *          zero otherwise.
3643  */
3644 CINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B);
3645 
3646 /**
3647  * Return the canonical type for a CXType.
3648  *
3649  * Clang's type system explicitly models typedefs and all the ways
3650  * a specific type can be represented.  The canonical type is the underlying
3651  * type with all the "sugar" removed.  For example, if 'T' is a typedef
3652  * for 'int', the canonical type for 'T' would be 'int'.
3653  */
3654 CINDEX_LINKAGE CXType clang_getCanonicalType(CXType T);
3655 
3656 /**
3657  * Determine whether a CXType has the "const" qualifier set,
3658  * without looking through typedefs that may have added "const" at a
3659  * different level.
3660  */
3661 CINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T);
3662 
3663 /**
3664  * Determine whether a  CXCursor that is a macro, is
3665  * function like.
3666  */
3667 CINDEX_LINKAGE unsigned clang_Cursor_isMacroFunctionLike(CXCursor C);
3668 
3669 /**
3670  * Determine whether a  CXCursor that is a macro, is a
3671  * builtin one.
3672  */
3673 CINDEX_LINKAGE unsigned clang_Cursor_isMacroBuiltin(CXCursor C);
3674 
3675 /**
3676  * Determine whether a  CXCursor that is a function declaration, is an
3677  * inline declaration.
3678  */
3679 CINDEX_LINKAGE unsigned clang_Cursor_isFunctionInlined(CXCursor C);
3680 
3681 /**
3682  * Determine whether a CXType has the "volatile" qualifier set,
3683  * without looking through typedefs that may have added "volatile" at
3684  * a different level.
3685  */
3686 CINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T);
3687 
3688 /**
3689  * Determine whether a CXType has the "restrict" qualifier set,
3690  * without looking through typedefs that may have added "restrict" at a
3691  * different level.
3692  */
3693 CINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T);
3694 
3695 /**
3696  * Returns the address space of the given type.
3697  */
3698 CINDEX_LINKAGE unsigned clang_getAddressSpace(CXType T);
3699 
3700 /**
3701  * Returns the typedef name of the given type.
3702  */
3703 CINDEX_LINKAGE CXString clang_getTypedefName(CXType CT);
3704 
3705 /**
3706  * For pointer types, returns the type of the pointee.
3707  */
3708 CINDEX_LINKAGE CXType clang_getPointeeType(CXType T);
3709 
3710 /**
3711  * Return the cursor for the declaration of the given type.
3712  */
3713 CINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T);
3714 
3715 /**
3716  * Returns the Objective-C type encoding for the specified declaration.
3717  */
3718 CINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C);
3719 
3720 /**
3721  * Returns the Objective-C type encoding for the specified CXType.
3722  */
3723 CINDEX_LINKAGE CXString clang_Type_getObjCEncoding(CXType type);
3724 
3725 /**
3726  * Retrieve the spelling of a given CXTypeKind.
3727  */
3728 CINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K);
3729 
3730 /**
3731  * Retrieve the calling convention associated with a function type.
3732  *
3733  * If a non-function type is passed in, CXCallingConv_Invalid is returned.
3734  */
3735 CINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T);
3736 
3737 /**
3738  * Retrieve the return type associated with a function type.
3739  *
3740  * If a non-function type is passed in, an invalid type is returned.
3741  */
3742 CINDEX_LINKAGE CXType clang_getResultType(CXType T);
3743 
3744 /**
3745  * Retrieve the exception specification type associated with a function type.
3746  * This is a value of type CXCursor_ExceptionSpecificationKind.
3747  *
3748  * If a non-function type is passed in, an error code of -1 is returned.
3749  */
3750 CINDEX_LINKAGE int clang_getExceptionSpecificationType(CXType T);
3751 
3752 /**
3753  * Retrieve the number of non-variadic parameters associated with a
3754  * function type.
3755  *
3756  * If a non-function type is passed in, -1 is returned.
3757  */
3758 CINDEX_LINKAGE int clang_getNumArgTypes(CXType T);
3759 
3760 /**
3761  * Retrieve the type of a parameter of a function type.
3762  *
3763  * If a non-function type is passed in or the function does not have enough
3764  * parameters, an invalid type is returned.
3765  */
3766 CINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i);
3767 
3768 /**
3769  * Retrieves the base type of the ObjCObjectType.
3770  *
3771  * If the type is not an ObjC object, an invalid type is returned.
3772  */
3773 CINDEX_LINKAGE CXType clang_Type_getObjCObjectBaseType(CXType T);
3774 
3775 /**
3776  * Retrieve the number of protocol references associated with an ObjC object/id.
3777  *
3778  * If the type is not an ObjC object, 0 is returned.
3779  */
3780 CINDEX_LINKAGE unsigned clang_Type_getNumObjCProtocolRefs(CXType T);
3781 
3782 /**
3783  * Retrieve the decl for a protocol reference for an ObjC object/id.
3784  *
3785  * If the type is not an ObjC object or there are not enough protocol
3786  * references, an invalid cursor is returned.
3787  */
3788 CINDEX_LINKAGE CXCursor clang_Type_getObjCProtocolDecl(CXType T, unsigned i);
3789 
3790 /**
3791  * Retrieve the number of type arguments associated with an ObjC object.
3792  *
3793  * If the type is not an ObjC object, 0 is returned.
3794  */
3795 CINDEX_LINKAGE unsigned clang_Type_getNumObjCTypeArgs(CXType T);
3796 
3797 /**
3798  * Retrieve a type argument associated with an ObjC object.
3799  *
3800  * If the type is not an ObjC or the index is not valid,
3801  * an invalid type is returned.
3802  */
3803 CINDEX_LINKAGE CXType clang_Type_getObjCTypeArg(CXType T, unsigned i);
3804 
3805 /**
3806  * Return 1 if the CXType is a variadic function type, and 0 otherwise.
3807  */
3808 CINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T);
3809 
3810 /**
3811  * Retrieve the return type associated with a given cursor.
3812  *
3813  * This only returns a valid type if the cursor refers to a function or method.
3814  */
3815 CINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C);
3816 
3817 /**
3818  * Retrieve the exception specification type associated with a given cursor.
3819  * This is a value of type CXCursor_ExceptionSpecificationKind.
3820  *
3821  * This only returns a valid result if the cursor refers to a function or
3822  * method.
3823  */
3824 CINDEX_LINKAGE int clang_getCursorExceptionSpecificationType(CXCursor C);
3825 
3826 /**
3827  * Return 1 if the CXType is a POD (plain old data) type, and 0
3828  *  otherwise.
3829  */
3830 CINDEX_LINKAGE unsigned clang_isPODType(CXType T);
3831 
3832 /**
3833  * Return the element type of an array, complex, or vector type.
3834  *
3835  * If a type is passed in that is not an array, complex, or vector type,
3836  * an invalid type is returned.
3837  */
3838 CINDEX_LINKAGE CXType clang_getElementType(CXType T);
3839 
3840 /**
3841  * Return the number of elements of an array or vector type.
3842  *
3843  * If a type is passed in that is not an array or vector type,
3844  * -1 is returned.
3845  */
3846 CINDEX_LINKAGE long long clang_getNumElements(CXType T);
3847 
3848 /**
3849  * Return the element type of an array type.
3850  *
3851  * If a non-array type is passed in, an invalid type is returned.
3852  */
3853 CINDEX_LINKAGE CXType clang_getArrayElementType(CXType T);
3854 
3855 /**
3856  * Return the array size of a constant array.
3857  *
3858  * If a non-array type is passed in, -1 is returned.
3859  */
3860 CINDEX_LINKAGE long long clang_getArraySize(CXType T);
3861 
3862 /**
3863  * Retrieve the type named by the qualified-id.
3864  *
3865  * If a non-elaborated type is passed in, an invalid type is returned.
3866  */
3867 CINDEX_LINKAGE CXType clang_Type_getNamedType(CXType T);
3868 
3869 /**
3870  * Determine if a typedef is 'transparent' tag.
3871  *
3872  * A typedef is considered 'transparent' if it shares a name and spelling
3873  * location with its underlying tag type, as is the case with the NS_ENUM macro.
3874  *
3875  * \returns non-zero if transparent and zero otherwise.
3876  */
3877 CINDEX_LINKAGE unsigned clang_Type_isTransparentTagTypedef(CXType T);
3878 
3879 enum CXTypeNullabilityKind {
3880   /**
3881    * Values of this type can never be null.
3882    */
3883   CXTypeNullability_NonNull = 0,
3884   /**
3885    * Values of this type can be null.
3886    */
3887   CXTypeNullability_Nullable = 1,
3888   /**
3889    * Whether values of this type can be null is (explicitly)
3890    * unspecified. This captures a (fairly rare) case where we
3891    * can't conclude anything about the nullability of the type even
3892    * though it has been considered.
3893    */
3894   CXTypeNullability_Unspecified = 2,
3895   /**
3896    * Nullability is not applicable to this type.
3897    */
3898   CXTypeNullability_Invalid = 3,
3899 
3900   /**
3901    * Generally behaves like Nullable, except when used in a block parameter that
3902    * was imported into a swift async method. There, swift will assume that the
3903    * parameter can get null even if no error occured. _Nullable parameters are
3904    * assumed to only get null on error.
3905    */
3906   CXTypeNullability_NullableResult = 4
3907 };
3908 
3909 /**
3910  * Retrieve the nullability kind of a pointer type.
3911  */
3912 CINDEX_LINKAGE enum CXTypeNullabilityKind clang_Type_getNullability(CXType T);
3913 
3914 /**
3915  * List the possible error codes for \c clang_Type_getSizeOf,
3916  *   \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and
3917  *   \c clang_Cursor_getOffsetOf.
3918  *
3919  * A value of this enumeration type can be returned if the target type is not
3920  * a valid argument to sizeof, alignof or offsetof.
3921  */
3922 enum CXTypeLayoutError {
3923   /**
3924    * Type is of kind CXType_Invalid.
3925    */
3926   CXTypeLayoutError_Invalid = -1,
3927   /**
3928    * The type is an incomplete Type.
3929    */
3930   CXTypeLayoutError_Incomplete = -2,
3931   /**
3932    * The type is a dependent Type.
3933    */
3934   CXTypeLayoutError_Dependent = -3,
3935   /**
3936    * The type is not a constant size type.
3937    */
3938   CXTypeLayoutError_NotConstantSize = -4,
3939   /**
3940    * The Field name is not valid for this record.
3941    */
3942   CXTypeLayoutError_InvalidFieldName = -5,
3943   /**
3944    * The type is undeduced.
3945    */
3946   CXTypeLayoutError_Undeduced = -6
3947 };
3948 
3949 /**
3950  * Return the alignment of a type in bytes as per C++[expr.alignof]
3951  *   standard.
3952  *
3953  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3954  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3955  *   is returned.
3956  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3957  *   returned.
3958  * If the type declaration is not a constant size type,
3959  *   CXTypeLayoutError_NotConstantSize is returned.
3960  */
3961 CINDEX_LINKAGE long long clang_Type_getAlignOf(CXType T);
3962 
3963 /**
3964  * Return the class type of an member pointer type.
3965  *
3966  * If a non-member-pointer type is passed in, an invalid type is returned.
3967  */
3968 CINDEX_LINKAGE CXType clang_Type_getClassType(CXType T);
3969 
3970 /**
3971  * Return the size of a type in bytes as per C++[expr.sizeof] standard.
3972  *
3973  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3974  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3975  *   is returned.
3976  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3977  *   returned.
3978  */
3979 CINDEX_LINKAGE long long clang_Type_getSizeOf(CXType T);
3980 
3981 /**
3982  * Return the offset of a field named S in a record of type T in bits
3983  *   as it would be returned by __offsetof__ as per C++11[18.2p4]
3984  *
3985  * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid
3986  *   is returned.
3987  * If the field's type declaration is an incomplete type,
3988  *   CXTypeLayoutError_Incomplete is returned.
3989  * If the field's type declaration is a dependent type,
3990  *   CXTypeLayoutError_Dependent is returned.
3991  * If the field's name S is not found,
3992  *   CXTypeLayoutError_InvalidFieldName is returned.
3993  */
3994 CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S);
3995 
3996 /**
3997  * Return the type that was modified by this attributed type.
3998  *
3999  * If the type is not an attributed type, an invalid type is returned.
4000  */
4001 CINDEX_LINKAGE CXType clang_Type_getModifiedType(CXType T);
4002 
4003 /**
4004  * Gets the type contained by this atomic type.
4005  *
4006  * If a non-atomic type is passed in, an invalid type is returned.
4007  */
4008 CINDEX_LINKAGE CXType clang_Type_getValueType(CXType CT);
4009 
4010 /**
4011  * Return the offset of the field represented by the Cursor.
4012  *
4013  * If the cursor is not a field declaration, -1 is returned.
4014  * If the cursor semantic parent is not a record field declaration,
4015  *   CXTypeLayoutError_Invalid is returned.
4016  * If the field's type declaration is an incomplete type,
4017  *   CXTypeLayoutError_Incomplete is returned.
4018  * If the field's type declaration is a dependent type,
4019  *   CXTypeLayoutError_Dependent is returned.
4020  * If the field's name S is not found,
4021  *   CXTypeLayoutError_InvalidFieldName is returned.
4022  */
4023 CINDEX_LINKAGE long long clang_Cursor_getOffsetOfField(CXCursor C);
4024 
4025 /**
4026  * Determine whether the given cursor represents an anonymous
4027  * tag or namespace
4028  */
4029 CINDEX_LINKAGE unsigned clang_Cursor_isAnonymous(CXCursor C);
4030 
4031 /**
4032  * Determine whether the given cursor represents an anonymous record
4033  * declaration.
4034  */
4035 CINDEX_LINKAGE unsigned clang_Cursor_isAnonymousRecordDecl(CXCursor C);
4036 
4037 /**
4038  * Determine whether the given cursor represents an inline namespace
4039  * declaration.
4040  */
4041 CINDEX_LINKAGE unsigned clang_Cursor_isInlineNamespace(CXCursor C);
4042 
4043 enum CXRefQualifierKind {
4044   /** No ref-qualifier was provided. */
4045   CXRefQualifier_None = 0,
4046   /** An lvalue ref-qualifier was provided (\c &). */
4047   CXRefQualifier_LValue,
4048   /** An rvalue ref-qualifier was provided (\c &&). */
4049   CXRefQualifier_RValue
4050 };
4051 
4052 /**
4053  * Returns the number of template arguments for given template
4054  * specialization, or -1 if type \c T is not a template specialization.
4055  */
4056 CINDEX_LINKAGE int clang_Type_getNumTemplateArguments(CXType T);
4057 
4058 /**
4059  * Returns the type template argument of a template class specialization
4060  * at given index.
4061  *
4062  * This function only returns template type arguments and does not handle
4063  * template template arguments or variadic packs.
4064  */
4065 CINDEX_LINKAGE CXType clang_Type_getTemplateArgumentAsType(CXType T,
4066                                                            unsigned i);
4067 
4068 /**
4069  * Retrieve the ref-qualifier kind of a function or method.
4070  *
4071  * The ref-qualifier is returned for C++ functions or methods. For other types
4072  * or non-C++ declarations, CXRefQualifier_None is returned.
4073  */
4074 CINDEX_LINKAGE enum CXRefQualifierKind clang_Type_getCXXRefQualifier(CXType T);
4075 
4076 /**
4077  * Returns non-zero if the cursor specifies a Record member that is a
4078  *   bitfield.
4079  */
4080 CINDEX_LINKAGE unsigned clang_Cursor_isBitField(CXCursor C);
4081 
4082 /**
4083  * Returns 1 if the base class specified by the cursor with kind
4084  *   CX_CXXBaseSpecifier is virtual.
4085  */
4086 CINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor);
4087 
4088 /**
4089  * Represents the C++ access control level to a base class for a
4090  * cursor with kind CX_CXXBaseSpecifier.
4091  */
4092 enum CX_CXXAccessSpecifier {
4093   CX_CXXInvalidAccessSpecifier,
4094   CX_CXXPublic,
4095   CX_CXXProtected,
4096   CX_CXXPrivate
4097 };
4098 
4099 /**
4100  * Returns the access control level for the referenced object.
4101  *
4102  * If the cursor refers to a C++ declaration, its access control level within
4103  * its parent scope is returned. Otherwise, if the cursor refers to a base
4104  * specifier or access specifier, the specifier itself is returned.
4105  */
4106 CINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor);
4107 
4108 /**
4109  * Represents the storage classes as declared in the source. CX_SC_Invalid
4110  * was added for the case that the passed cursor in not a declaration.
4111  */
4112 enum CX_StorageClass {
4113   CX_SC_Invalid,
4114   CX_SC_None,
4115   CX_SC_Extern,
4116   CX_SC_Static,
4117   CX_SC_PrivateExtern,
4118   CX_SC_OpenCLWorkGroupLocal,
4119   CX_SC_Auto,
4120   CX_SC_Register
4121 };
4122 
4123 /**
4124  * Returns the storage class for a function or variable declaration.
4125  *
4126  * If the passed in Cursor is not a function or variable declaration,
4127  * CX_SC_Invalid is returned else the storage class.
4128  */
4129 CINDEX_LINKAGE enum CX_StorageClass clang_Cursor_getStorageClass(CXCursor);
4130 
4131 /**
4132  * Determine the number of overloaded declarations referenced by a
4133  * \c CXCursor_OverloadedDeclRef cursor.
4134  *
4135  * \param cursor The cursor whose overloaded declarations are being queried.
4136  *
4137  * \returns The number of overloaded declarations referenced by \c cursor. If it
4138  * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0.
4139  */
4140 CINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor);
4141 
4142 /**
4143  * Retrieve a cursor for one of the overloaded declarations referenced
4144  * by a \c CXCursor_OverloadedDeclRef cursor.
4145  *
4146  * \param cursor The cursor whose overloaded declarations are being queried.
4147  *
4148  * \param index The zero-based index into the set of overloaded declarations in
4149  * the cursor.
4150  *
4151  * \returns A cursor representing the declaration referenced by the given
4152  * \c cursor at the specified \c index. If the cursor does not have an
4153  * associated set of overloaded declarations, or if the index is out of bounds,
4154  * returns \c clang_getNullCursor();
4155  */
4156 CINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor,
4157                                                 unsigned index);
4158 
4159 /**
4160  * @}
4161  */
4162 
4163 /**
4164  * \defgroup CINDEX_ATTRIBUTES Information for attributes
4165  *
4166  * @{
4167  */
4168 
4169 /**
4170  * For cursors representing an iboutletcollection attribute,
4171  *  this function returns the collection element type.
4172  *
4173  */
4174 CINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor);
4175 
4176 /**
4177  * @}
4178  */
4179 
4180 /**
4181  * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
4182  *
4183  * These routines provide the ability to traverse the abstract syntax tree
4184  * using cursors.
4185  *
4186  * @{
4187  */
4188 
4189 /**
4190  * Describes how the traversal of the children of a particular
4191  * cursor should proceed after visiting a particular child cursor.
4192  *
4193  * A value of this enumeration type should be returned by each
4194  * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
4195  */
4196 enum CXChildVisitResult {
4197   /**
4198    * Terminates the cursor traversal.
4199    */
4200   CXChildVisit_Break,
4201   /**
4202    * Continues the cursor traversal with the next sibling of
4203    * the cursor just visited, without visiting its children.
4204    */
4205   CXChildVisit_Continue,
4206   /**
4207    * Recursively traverse the children of this cursor, using
4208    * the same visitor and client data.
4209    */
4210   CXChildVisit_Recurse
4211 };
4212 
4213 /**
4214  * Visitor invoked for each cursor found by a traversal.
4215  *
4216  * This visitor function will be invoked for each cursor found by
4217  * clang_visitCursorChildren(). Its first argument is the cursor being
4218  * visited, its second argument is the parent visitor for that cursor,
4219  * and its third argument is the client data provided to
4220  * clang_visitCursorChildren().
4221  *
4222  * The visitor should return one of the \c CXChildVisitResult values
4223  * to direct clang_visitCursorChildren().
4224  */
4225 typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor,
4226                                                    CXCursor parent,
4227                                                    CXClientData client_data);
4228 
4229 /**
4230  * Visit the children of a particular cursor.
4231  *
4232  * This function visits all the direct children of the given cursor,
4233  * invoking the given \p visitor function with the cursors of each
4234  * visited child. The traversal may be recursive, if the visitor returns
4235  * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
4236  * the visitor returns \c CXChildVisit_Break.
4237  *
4238  * \param parent the cursor whose child may be visited. All kinds of
4239  * cursors can be visited, including invalid cursors (which, by
4240  * definition, have no children).
4241  *
4242  * \param visitor the visitor function that will be invoked for each
4243  * child of \p parent.
4244  *
4245  * \param client_data pointer data supplied by the client, which will
4246  * be passed to the visitor each time it is invoked.
4247  *
4248  * \returns a non-zero value if the traversal was terminated
4249  * prematurely by the visitor returning \c CXChildVisit_Break.
4250  */
4251 CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent,
4252                                             CXCursorVisitor visitor,
4253                                             CXClientData client_data);
4254 #ifdef __has_feature
4255 #if __has_feature(blocks)
4256 /**
4257  * Visitor invoked for each cursor found by a traversal.
4258  *
4259  * This visitor block will be invoked for each cursor found by
4260  * clang_visitChildrenWithBlock(). Its first argument is the cursor being
4261  * visited, its second argument is the parent visitor for that cursor.
4262  *
4263  * The visitor should return one of the \c CXChildVisitResult values
4264  * to direct clang_visitChildrenWithBlock().
4265  */
4266 typedef enum CXChildVisitResult (^CXCursorVisitorBlock)(CXCursor cursor,
4267                                                         CXCursor parent);
4268 
4269 /**
4270  * Visits the children of a cursor using the specified block.  Behaves
4271  * identically to clang_visitChildren() in all other respects.
4272  */
4273 CINDEX_LINKAGE unsigned
4274 clang_visitChildrenWithBlock(CXCursor parent, CXCursorVisitorBlock block);
4275 #endif
4276 #endif
4277 
4278 /**
4279  * @}
4280  */
4281 
4282 /**
4283  * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
4284  *
4285  * These routines provide the ability to determine references within and
4286  * across translation units, by providing the names of the entities referenced
4287  * by cursors, follow reference cursors to the declarations they reference,
4288  * and associate declarations with their definitions.
4289  *
4290  * @{
4291  */
4292 
4293 /**
4294  * Retrieve a Unified Symbol Resolution (USR) for the entity referenced
4295  * by the given cursor.
4296  *
4297  * A Unified Symbol Resolution (USR) is a string that identifies a particular
4298  * entity (function, class, variable, etc.) within a program. USRs can be
4299  * compared across translation units to determine, e.g., when references in
4300  * one translation refer to an entity defined in another translation unit.
4301  */
4302 CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor);
4303 
4304 /**
4305  * Construct a USR for a specified Objective-C class.
4306  */
4307 CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
4308 
4309 /**
4310  * Construct a USR for a specified Objective-C category.
4311  */
4312 CINDEX_LINKAGE CXString clang_constructUSR_ObjCCategory(
4313     const char *class_name, const char *category_name);
4314 
4315 /**
4316  * Construct a USR for a specified Objective-C protocol.
4317  */
4318 CINDEX_LINKAGE CXString
4319 clang_constructUSR_ObjCProtocol(const char *protocol_name);
4320 
4321 /**
4322  * Construct a USR for a specified Objective-C instance variable and
4323  *   the USR for its containing class.
4324  */
4325 CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name,
4326                                                     CXString classUSR);
4327 
4328 /**
4329  * Construct a USR for a specified Objective-C method and
4330  *   the USR for its containing class.
4331  */
4332 CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name,
4333                                                       unsigned isInstanceMethod,
4334                                                       CXString classUSR);
4335 
4336 /**
4337  * Construct a USR for a specified Objective-C property and the USR
4338  *  for its containing class.
4339  */
4340 CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property,
4341                                                         CXString classUSR);
4342 
4343 /**
4344  * Retrieve a name for the entity referenced by this cursor.
4345  */
4346 CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor);
4347 
4348 /**
4349  * Retrieve a range for a piece that forms the cursors spelling name.
4350  * Most of the times there is only one range for the complete spelling but for
4351  * Objective-C methods and Objective-C message expressions, there are multiple
4352  * pieces for each selector identifier.
4353  *
4354  * \param pieceIndex the index of the spelling name piece. If this is greater
4355  * than the actual number of pieces, it will return a NULL (invalid) range.
4356  *
4357  * \param options Reserved.
4358  */
4359 CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(
4360     CXCursor, unsigned pieceIndex, unsigned options);
4361 
4362 /**
4363  * Opaque pointer representing a policy that controls pretty printing
4364  * for \c clang_getCursorPrettyPrinted.
4365  */
4366 typedef void *CXPrintingPolicy;
4367 
4368 /**
4369  * Properties for the printing policy.
4370  *
4371  * See \c clang::PrintingPolicy for more information.
4372  */
4373 enum CXPrintingPolicyProperty {
4374   CXPrintingPolicy_Indentation,
4375   CXPrintingPolicy_SuppressSpecifiers,
4376   CXPrintingPolicy_SuppressTagKeyword,
4377   CXPrintingPolicy_IncludeTagDefinition,
4378   CXPrintingPolicy_SuppressScope,
4379   CXPrintingPolicy_SuppressUnwrittenScope,
4380   CXPrintingPolicy_SuppressInitializers,
4381   CXPrintingPolicy_ConstantArraySizeAsWritten,
4382   CXPrintingPolicy_AnonymousTagLocations,
4383   CXPrintingPolicy_SuppressStrongLifetime,
4384   CXPrintingPolicy_SuppressLifetimeQualifiers,
4385   CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors,
4386   CXPrintingPolicy_Bool,
4387   CXPrintingPolicy_Restrict,
4388   CXPrintingPolicy_Alignof,
4389   CXPrintingPolicy_UnderscoreAlignof,
4390   CXPrintingPolicy_UseVoidForZeroParams,
4391   CXPrintingPolicy_TerseOutput,
4392   CXPrintingPolicy_PolishForDeclaration,
4393   CXPrintingPolicy_Half,
4394   CXPrintingPolicy_MSWChar,
4395   CXPrintingPolicy_IncludeNewlines,
4396   CXPrintingPolicy_MSVCFormatting,
4397   CXPrintingPolicy_ConstantsAsWritten,
4398   CXPrintingPolicy_SuppressImplicitBase,
4399   CXPrintingPolicy_FullyQualifiedName,
4400 
4401   CXPrintingPolicy_LastProperty = CXPrintingPolicy_FullyQualifiedName
4402 };
4403 
4404 /**
4405  * Get a property value for the given printing policy.
4406  */
4407 CINDEX_LINKAGE unsigned
4408 clang_PrintingPolicy_getProperty(CXPrintingPolicy Policy,
4409                                  enum CXPrintingPolicyProperty Property);
4410 
4411 /**
4412  * Set a property value for the given printing policy.
4413  */
4414 CINDEX_LINKAGE void
4415 clang_PrintingPolicy_setProperty(CXPrintingPolicy Policy,
4416                                  enum CXPrintingPolicyProperty Property,
4417                                  unsigned Value);
4418 
4419 /**
4420  * Retrieve the default policy for the cursor.
4421  *
4422  * The policy should be released after use with \c
4423  * clang_PrintingPolicy_dispose.
4424  */
4425 CINDEX_LINKAGE CXPrintingPolicy clang_getCursorPrintingPolicy(CXCursor);
4426 
4427 /**
4428  * Release a printing policy.
4429  */
4430 CINDEX_LINKAGE void clang_PrintingPolicy_dispose(CXPrintingPolicy Policy);
4431 
4432 /**
4433  * Pretty print declarations.
4434  *
4435  * \param Cursor The cursor representing a declaration.
4436  *
4437  * \param Policy The policy to control the entities being printed. If
4438  * NULL, a default policy is used.
4439  *
4440  * \returns The pretty printed declaration or the empty string for
4441  * other cursors.
4442  */
4443 CINDEX_LINKAGE CXString clang_getCursorPrettyPrinted(CXCursor Cursor,
4444                                                      CXPrintingPolicy Policy);
4445 
4446 /**
4447  * Retrieve the display name for the entity referenced by this cursor.
4448  *
4449  * The display name contains extra information that helps identify the cursor,
4450  * such as the parameters of a function or template or the arguments of a
4451  * class template specialization.
4452  */
4453 CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor);
4454 
4455 /** For a cursor that is a reference, retrieve a cursor representing the
4456  * entity that it references.
4457  *
4458  * Reference cursors refer to other entities in the AST. For example, an
4459  * Objective-C superclass reference cursor refers to an Objective-C class.
4460  * This function produces the cursor for the Objective-C class from the
4461  * cursor for the superclass reference. If the input cursor is a declaration or
4462  * definition, it returns that declaration or definition unchanged.
4463  * Otherwise, returns the NULL cursor.
4464  */
4465 CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor);
4466 
4467 /**
4468  *  For a cursor that is either a reference to or a declaration
4469  *  of some entity, retrieve a cursor that describes the definition of
4470  *  that entity.
4471  *
4472  *  Some entities can be declared multiple times within a translation
4473  *  unit, but only one of those declarations can also be a
4474  *  definition. For example, given:
4475  *
4476  *  \code
4477  *  int f(int, int);
4478  *  int g(int x, int y) { return f(x, y); }
4479  *  int f(int a, int b) { return a + b; }
4480  *  int f(int, int);
4481  *  \endcode
4482  *
4483  *  there are three declarations of the function "f", but only the
4484  *  second one is a definition. The clang_getCursorDefinition()
4485  *  function will take any cursor pointing to a declaration of "f"
4486  *  (the first or fourth lines of the example) or a cursor referenced
4487  *  that uses "f" (the call to "f' inside "g") and will return a
4488  *  declaration cursor pointing to the definition (the second "f"
4489  *  declaration).
4490  *
4491  *  If given a cursor for which there is no corresponding definition,
4492  *  e.g., because there is no definition of that entity within this
4493  *  translation unit, returns a NULL cursor.
4494  */
4495 CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor);
4496 
4497 /**
4498  * Determine whether the declaration pointed to by this cursor
4499  * is also a definition of that entity.
4500  */
4501 CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor);
4502 
4503 /**
4504  * Retrieve the canonical cursor corresponding to the given cursor.
4505  *
4506  * In the C family of languages, many kinds of entities can be declared several
4507  * times within a single translation unit. For example, a structure type can
4508  * be forward-declared (possibly multiple times) and later defined:
4509  *
4510  * \code
4511  * struct X;
4512  * struct X;
4513  * struct X {
4514  *   int member;
4515  * };
4516  * \endcode
4517  *
4518  * The declarations and the definition of \c X are represented by three
4519  * different cursors, all of which are declarations of the same underlying
4520  * entity. One of these cursor is considered the "canonical" cursor, which
4521  * is effectively the representative for the underlying entity. One can
4522  * determine if two cursors are declarations of the same underlying entity by
4523  * comparing their canonical cursors.
4524  *
4525  * \returns The canonical cursor for the entity referred to by the given cursor.
4526  */
4527 CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor);
4528 
4529 /**
4530  * If the cursor points to a selector identifier in an Objective-C
4531  * method or message expression, this returns the selector index.
4532  *
4533  * After getting a cursor with #clang_getCursor, this can be called to
4534  * determine if the location points to a selector identifier.
4535  *
4536  * \returns The selector index if the cursor is an Objective-C method or message
4537  * expression and the cursor is pointing to a selector identifier, or -1
4538  * otherwise.
4539  */
4540 CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor);
4541 
4542 /**
4543  * Given a cursor pointing to a C++ method call or an Objective-C
4544  * message, returns non-zero if the method/message is "dynamic", meaning:
4545  *
4546  * For a C++ method: the call is virtual.
4547  * For an Objective-C message: the receiver is an object instance, not 'super'
4548  * or a specific class.
4549  *
4550  * If the method/message is "static" or the cursor does not point to a
4551  * method/message, it will return zero.
4552  */
4553 CINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C);
4554 
4555 /**
4556  * Given a cursor pointing to an Objective-C message or property
4557  * reference, or C++ method call, returns the CXType of the receiver.
4558  */
4559 CINDEX_LINKAGE CXType clang_Cursor_getReceiverType(CXCursor C);
4560 
4561 /**
4562  * Property attributes for a \c CXCursor_ObjCPropertyDecl.
4563  */
4564 typedef enum {
4565   CXObjCPropertyAttr_noattr = 0x00,
4566   CXObjCPropertyAttr_readonly = 0x01,
4567   CXObjCPropertyAttr_getter = 0x02,
4568   CXObjCPropertyAttr_assign = 0x04,
4569   CXObjCPropertyAttr_readwrite = 0x08,
4570   CXObjCPropertyAttr_retain = 0x10,
4571   CXObjCPropertyAttr_copy = 0x20,
4572   CXObjCPropertyAttr_nonatomic = 0x40,
4573   CXObjCPropertyAttr_setter = 0x80,
4574   CXObjCPropertyAttr_atomic = 0x100,
4575   CXObjCPropertyAttr_weak = 0x200,
4576   CXObjCPropertyAttr_strong = 0x400,
4577   CXObjCPropertyAttr_unsafe_unretained = 0x800,
4578   CXObjCPropertyAttr_class = 0x1000
4579 } CXObjCPropertyAttrKind;
4580 
4581 /**
4582  * Given a cursor that represents a property declaration, return the
4583  * associated property attributes. The bits are formed from
4584  * \c CXObjCPropertyAttrKind.
4585  *
4586  * \param reserved Reserved for future use, pass 0.
4587  */
4588 CINDEX_LINKAGE unsigned
4589 clang_Cursor_getObjCPropertyAttributes(CXCursor C, unsigned reserved);
4590 
4591 /**
4592  * Given a cursor that represents a property declaration, return the
4593  * name of the method that implements the getter.
4594  */
4595 CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertyGetterName(CXCursor C);
4596 
4597 /**
4598  * Given a cursor that represents a property declaration, return the
4599  * name of the method that implements the setter, if any.
4600  */
4601 CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertySetterName(CXCursor C);
4602 
4603 /**
4604  * 'Qualifiers' written next to the return and parameter types in
4605  * Objective-C method declarations.
4606  */
4607 typedef enum {
4608   CXObjCDeclQualifier_None = 0x0,
4609   CXObjCDeclQualifier_In = 0x1,
4610   CXObjCDeclQualifier_Inout = 0x2,
4611   CXObjCDeclQualifier_Out = 0x4,
4612   CXObjCDeclQualifier_Bycopy = 0x8,
4613   CXObjCDeclQualifier_Byref = 0x10,
4614   CXObjCDeclQualifier_Oneway = 0x20
4615 } CXObjCDeclQualifierKind;
4616 
4617 /**
4618  * Given a cursor that represents an Objective-C method or parameter
4619  * declaration, return the associated Objective-C qualifiers for the return
4620  * type or the parameter respectively. The bits are formed from
4621  * CXObjCDeclQualifierKind.
4622  */
4623 CINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers(CXCursor C);
4624 
4625 /**
4626  * Given a cursor that represents an Objective-C method or property
4627  * declaration, return non-zero if the declaration was affected by "\@optional".
4628  * Returns zero if the cursor is not such a declaration or it is "\@required".
4629  */
4630 CINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional(CXCursor C);
4631 
4632 /**
4633  * Returns non-zero if the given cursor is a variadic function or method.
4634  */
4635 CINDEX_LINKAGE unsigned clang_Cursor_isVariadic(CXCursor C);
4636 
4637 /**
4638  * Returns non-zero if the given cursor points to a symbol marked with
4639  * external_source_symbol attribute.
4640  *
4641  * \param language If non-NULL, and the attribute is present, will be set to
4642  * the 'language' string from the attribute.
4643  *
4644  * \param definedIn If non-NULL, and the attribute is present, will be set to
4645  * the 'definedIn' string from the attribute.
4646  *
4647  * \param isGenerated If non-NULL, and the attribute is present, will be set to
4648  * non-zero if the 'generated_declaration' is set in the attribute.
4649  */
4650 CINDEX_LINKAGE unsigned clang_Cursor_isExternalSymbol(CXCursor C,
4651                                                       CXString *language,
4652                                                       CXString *definedIn,
4653                                                       unsigned *isGenerated);
4654 
4655 /**
4656  * Given a cursor that represents a declaration, return the associated
4657  * comment's source range.  The range may include multiple consecutive comments
4658  * with whitespace in between.
4659  */
4660 CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange(CXCursor C);
4661 
4662 /**
4663  * Given a cursor that represents a declaration, return the associated
4664  * comment text, including comment markers.
4665  */
4666 CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C);
4667 
4668 /**
4669  * Given a cursor that represents a documentable entity (e.g.,
4670  * declaration), return the associated \paragraph; otherwise return the
4671  * first paragraph.
4672  */
4673 CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C);
4674 
4675 /**
4676  * @}
4677  */
4678 
4679 /** \defgroup CINDEX_MANGLE Name Mangling API Functions
4680  *
4681  * @{
4682  */
4683 
4684 /**
4685  * Retrieve the CXString representing the mangled name of the cursor.
4686  */
4687 CINDEX_LINKAGE CXString clang_Cursor_getMangling(CXCursor);
4688 
4689 /**
4690  * Retrieve the CXStrings representing the mangled symbols of the C++
4691  * constructor or destructor at the cursor.
4692  */
4693 CINDEX_LINKAGE CXStringSet *clang_Cursor_getCXXManglings(CXCursor);
4694 
4695 /**
4696  * Retrieve the CXStrings representing the mangled symbols of the ObjC
4697  * class interface or implementation at the cursor.
4698  */
4699 CINDEX_LINKAGE CXStringSet *clang_Cursor_getObjCManglings(CXCursor);
4700 
4701 /**
4702  * @}
4703  */
4704 
4705 /**
4706  * \defgroup CINDEX_MODULE Module introspection
4707  *
4708  * The functions in this group provide access to information about modules.
4709  *
4710  * @{
4711  */
4712 
4713 typedef void *CXModule;
4714 
4715 /**
4716  * Given a CXCursor_ModuleImportDecl cursor, return the associated module.
4717  */
4718 CINDEX_LINKAGE CXModule clang_Cursor_getModule(CXCursor C);
4719 
4720 /**
4721  * Given a CXFile header file, return the module that contains it, if one
4722  * exists.
4723  */
4724 CINDEX_LINKAGE CXModule clang_getModuleForFile(CXTranslationUnit, CXFile);
4725 
4726 /**
4727  * \param Module a module object.
4728  *
4729  * \returns the module file where the provided module object came from.
4730  */
4731 CINDEX_LINKAGE CXFile clang_Module_getASTFile(CXModule Module);
4732 
4733 /**
4734  * \param Module a module object.
4735  *
4736  * \returns the parent of a sub-module or NULL if the given module is top-level,
4737  * e.g. for 'std.vector' it will return the 'std' module.
4738  */
4739 CINDEX_LINKAGE CXModule clang_Module_getParent(CXModule Module);
4740 
4741 /**
4742  * \param Module a module object.
4743  *
4744  * \returns the name of the module, e.g. for the 'std.vector' sub-module it
4745  * will return "vector".
4746  */
4747 CINDEX_LINKAGE CXString clang_Module_getName(CXModule Module);
4748 
4749 /**
4750  * \param Module a module object.
4751  *
4752  * \returns the full name of the module, e.g. "std.vector".
4753  */
4754 CINDEX_LINKAGE CXString clang_Module_getFullName(CXModule Module);
4755 
4756 /**
4757  * \param Module a module object.
4758  *
4759  * \returns non-zero if the module is a system one.
4760  */
4761 CINDEX_LINKAGE int clang_Module_isSystem(CXModule Module);
4762 
4763 /**
4764  * \param Module a module object.
4765  *
4766  * \returns the number of top level headers associated with this module.
4767  */
4768 CINDEX_LINKAGE unsigned clang_Module_getNumTopLevelHeaders(CXTranslationUnit,
4769                                                            CXModule Module);
4770 
4771 /**
4772  * \param Module a module object.
4773  *
4774  * \param Index top level header index (zero-based).
4775  *
4776  * \returns the specified top level header associated with the module.
4777  */
4778 CINDEX_LINKAGE
4779 CXFile clang_Module_getTopLevelHeader(CXTranslationUnit, CXModule Module,
4780                                       unsigned Index);
4781 
4782 /**
4783  * @}
4784  */
4785 
4786 /**
4787  * \defgroup CINDEX_CPP C++ AST introspection
4788  *
4789  * The routines in this group provide access information in the ASTs specific
4790  * to C++ language features.
4791  *
4792  * @{
4793  */
4794 
4795 /**
4796  * Determine if a C++ constructor is a converting constructor.
4797  */
4798 CINDEX_LINKAGE unsigned
4799 clang_CXXConstructor_isConvertingConstructor(CXCursor C);
4800 
4801 /**
4802  * Determine if a C++ constructor is a copy constructor.
4803  */
4804 CINDEX_LINKAGE unsigned clang_CXXConstructor_isCopyConstructor(CXCursor C);
4805 
4806 /**
4807  * Determine if a C++ constructor is the default constructor.
4808  */
4809 CINDEX_LINKAGE unsigned clang_CXXConstructor_isDefaultConstructor(CXCursor C);
4810 
4811 /**
4812  * Determine if a C++ constructor is a move constructor.
4813  */
4814 CINDEX_LINKAGE unsigned clang_CXXConstructor_isMoveConstructor(CXCursor C);
4815 
4816 /**
4817  * Determine if a C++ field is declared 'mutable'.
4818  */
4819 CINDEX_LINKAGE unsigned clang_CXXField_isMutable(CXCursor C);
4820 
4821 /**
4822  * Determine if a C++ method is declared '= default'.
4823  */
4824 CINDEX_LINKAGE unsigned clang_CXXMethod_isDefaulted(CXCursor C);
4825 
4826 /**
4827  * Determine if a C++ member function or member function template is
4828  * pure virtual.
4829  */
4830 CINDEX_LINKAGE unsigned clang_CXXMethod_isPureVirtual(CXCursor C);
4831 
4832 /**
4833  * Determine if a C++ member function or member function template is
4834  * declared 'static'.
4835  */
4836 CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C);
4837 
4838 /**
4839  * Determine if a C++ member function or member function template is
4840  * explicitly declared 'virtual' or if it overrides a virtual method from
4841  * one of the base classes.
4842  */
4843 CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C);
4844 
4845 /**
4846  * Determine if a C++ record is abstract, i.e. whether a class or struct
4847  * has a pure virtual member function.
4848  */
4849 CINDEX_LINKAGE unsigned clang_CXXRecord_isAbstract(CXCursor C);
4850 
4851 /**
4852  * Determine if an enum declaration refers to a scoped enum.
4853  */
4854 CINDEX_LINKAGE unsigned clang_EnumDecl_isScoped(CXCursor C);
4855 
4856 /**
4857  * Determine if a C++ member function or member function template is
4858  * declared 'const'.
4859  */
4860 CINDEX_LINKAGE unsigned clang_CXXMethod_isConst(CXCursor C);
4861 
4862 /**
4863  * Given a cursor that represents a template, determine
4864  * the cursor kind of the specializations would be generated by instantiating
4865  * the template.
4866  *
4867  * This routine can be used to determine what flavor of function template,
4868  * class template, or class template partial specialization is stored in the
4869  * cursor. For example, it can describe whether a class template cursor is
4870  * declared with "struct", "class" or "union".
4871  *
4872  * \param C The cursor to query. This cursor should represent a template
4873  * declaration.
4874  *
4875  * \returns The cursor kind of the specializations that would be generated
4876  * by instantiating the template \p C. If \p C is not a template, returns
4877  * \c CXCursor_NoDeclFound.
4878  */
4879 CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C);
4880 
4881 /**
4882  * Given a cursor that may represent a specialization or instantiation
4883  * of a template, retrieve the cursor that represents the template that it
4884  * specializes or from which it was instantiated.
4885  *
4886  * This routine determines the template involved both for explicit
4887  * specializations of templates and for implicit instantiations of the template,
4888  * both of which are referred to as "specializations". For a class template
4889  * specialization (e.g., \c std::vector<bool>), this routine will return
4890  * either the primary template (\c std::vector) or, if the specialization was
4891  * instantiated from a class template partial specialization, the class template
4892  * partial specialization. For a class template partial specialization and a
4893  * function template specialization (including instantiations), this
4894  * this routine will return the specialized template.
4895  *
4896  * For members of a class template (e.g., member functions, member classes, or
4897  * static data members), returns the specialized or instantiated member.
4898  * Although not strictly "templates" in the C++ language, members of class
4899  * templates have the same notions of specializations and instantiations that
4900  * templates do, so this routine treats them similarly.
4901  *
4902  * \param C A cursor that may be a specialization of a template or a member
4903  * of a template.
4904  *
4905  * \returns If the given cursor is a specialization or instantiation of a
4906  * template or a member thereof, the template or member that it specializes or
4907  * from which it was instantiated. Otherwise, returns a NULL cursor.
4908  */
4909 CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C);
4910 
4911 /**
4912  * Given a cursor that references something else, return the source range
4913  * covering that reference.
4914  *
4915  * \param C A cursor pointing to a member reference, a declaration reference, or
4916  * an operator call.
4917  * \param NameFlags A bitset with three independent flags:
4918  * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and
4919  * CXNameRange_WantSinglePiece.
4920  * \param PieceIndex For contiguous names or when passing the flag
4921  * CXNameRange_WantSinglePiece, only one piece with index 0 is
4922  * available. When the CXNameRange_WantSinglePiece flag is not passed for a
4923  * non-contiguous names, this index can be used to retrieve the individual
4924  * pieces of the name. See also CXNameRange_WantSinglePiece.
4925  *
4926  * \returns The piece of the name pointed to by the given cursor. If there is no
4927  * name, or if the PieceIndex is out-of-range, a null-cursor will be returned.
4928  */
4929 CINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(
4930     CXCursor C, unsigned NameFlags, unsigned PieceIndex);
4931 
4932 enum CXNameRefFlags {
4933   /**
4934    * Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the
4935    * range.
4936    */
4937   CXNameRange_WantQualifier = 0x1,
4938 
4939   /**
4940    * Include the explicit template arguments, e.g. \<int> in x.f<int>,
4941    * in the range.
4942    */
4943   CXNameRange_WantTemplateArgs = 0x2,
4944 
4945   /**
4946    * If the name is non-contiguous, return the full spanning range.
4947    *
4948    * Non-contiguous names occur in Objective-C when a selector with two or more
4949    * parameters is used, or in C++ when using an operator:
4950    * \code
4951    * [object doSomething:here withValue:there]; // Objective-C
4952    * return some_vector[1]; // C++
4953    * \endcode
4954    */
4955   CXNameRange_WantSinglePiece = 0x4
4956 };
4957 
4958 /**
4959  * @}
4960  */
4961 
4962 /**
4963  * \defgroup CINDEX_LEX Token extraction and manipulation
4964  *
4965  * The routines in this group provide access to the tokens within a
4966  * translation unit, along with a semantic mapping of those tokens to
4967  * their corresponding cursors.
4968  *
4969  * @{
4970  */
4971 
4972 /**
4973  * Describes a kind of token.
4974  */
4975 typedef enum CXTokenKind {
4976   /**
4977    * A token that contains some kind of punctuation.
4978    */
4979   CXToken_Punctuation,
4980 
4981   /**
4982    * A language keyword.
4983    */
4984   CXToken_Keyword,
4985 
4986   /**
4987    * An identifier (that is not a keyword).
4988    */
4989   CXToken_Identifier,
4990 
4991   /**
4992    * A numeric, string, or character literal.
4993    */
4994   CXToken_Literal,
4995 
4996   /**
4997    * A comment.
4998    */
4999   CXToken_Comment
5000 } CXTokenKind;
5001 
5002 /**
5003  * Describes a single preprocessing token.
5004  */
5005 typedef struct {
5006   unsigned int_data[4];
5007   void *ptr_data;
5008 } CXToken;
5009 
5010 /**
5011  * Get the raw lexical token starting with the given location.
5012  *
5013  * \param TU the translation unit whose text is being tokenized.
5014  *
5015  * \param Location the source location with which the token starts.
5016  *
5017  * \returns The token starting with the given location or NULL if no such token
5018  * exist. The returned pointer must be freed with clang_disposeTokens before the
5019  * translation unit is destroyed.
5020  */
5021 CINDEX_LINKAGE CXToken *clang_getToken(CXTranslationUnit TU,
5022                                        CXSourceLocation Location);
5023 
5024 /**
5025  * Determine the kind of the given token.
5026  */
5027 CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken);
5028 
5029 /**
5030  * Determine the spelling of the given token.
5031  *
5032  * The spelling of a token is the textual representation of that token, e.g.,
5033  * the text of an identifier or keyword.
5034  */
5035 CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken);
5036 
5037 /**
5038  * Retrieve the source location of the given token.
5039  */
5040 CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit,
5041                                                        CXToken);
5042 
5043 /**
5044  * Retrieve a source range that covers the given token.
5045  */
5046 CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken);
5047 
5048 /**
5049  * Tokenize the source code described by the given range into raw
5050  * lexical tokens.
5051  *
5052  * \param TU the translation unit whose text is being tokenized.
5053  *
5054  * \param Range the source range in which text should be tokenized. All of the
5055  * tokens produced by tokenization will fall within this source range,
5056  *
5057  * \param Tokens this pointer will be set to point to the array of tokens
5058  * that occur within the given source range. The returned pointer must be
5059  * freed with clang_disposeTokens() before the translation unit is destroyed.
5060  *
5061  * \param NumTokens will be set to the number of tokens in the \c *Tokens
5062  * array.
5063  *
5064  */
5065 CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
5066                                    CXToken **Tokens, unsigned *NumTokens);
5067 
5068 /**
5069  * Annotate the given set of tokens by providing cursors for each token
5070  * that can be mapped to a specific entity within the abstract syntax tree.
5071  *
5072  * This token-annotation routine is equivalent to invoking
5073  * clang_getCursor() for the source locations of each of the
5074  * tokens. The cursors provided are filtered, so that only those
5075  * cursors that have a direct correspondence to the token are
5076  * accepted. For example, given a function call \c f(x),
5077  * clang_getCursor() would provide the following cursors:
5078  *
5079  *   * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
5080  *   * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
5081  *   * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
5082  *
5083  * Only the first and last of these cursors will occur within the
5084  * annotate, since the tokens "f" and "x' directly refer to a function
5085  * and a variable, respectively, but the parentheses are just a small
5086  * part of the full syntax of the function call expression, which is
5087  * not provided as an annotation.
5088  *
5089  * \param TU the translation unit that owns the given tokens.
5090  *
5091  * \param Tokens the set of tokens to annotate.
5092  *
5093  * \param NumTokens the number of tokens in \p Tokens.
5094  *
5095  * \param Cursors an array of \p NumTokens cursors, whose contents will be
5096  * replaced with the cursors corresponding to each token.
5097  */
5098 CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, CXToken *Tokens,
5099                                          unsigned NumTokens, CXCursor *Cursors);
5100 
5101 /**
5102  * Free the given set of tokens.
5103  */
5104 CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, CXToken *Tokens,
5105                                         unsigned NumTokens);
5106 
5107 /**
5108  * @}
5109  */
5110 
5111 /**
5112  * \defgroup CINDEX_DEBUG Debugging facilities
5113  *
5114  * These routines are used for testing and debugging, only, and should not
5115  * be relied upon.
5116  *
5117  * @{
5118  */
5119 
5120 /* for debug/testing */
5121 CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind);
5122 CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(
5123     CXCursor, const char **startBuf, const char **endBuf, unsigned *startLine,
5124     unsigned *startColumn, unsigned *endLine, unsigned *endColumn);
5125 CINDEX_LINKAGE void clang_enableStackTraces(void);
5126 CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void *), void *user_data,
5127                                           unsigned stack_size);
5128 
5129 /**
5130  * @}
5131  */
5132 
5133 /**
5134  * \defgroup CINDEX_CODE_COMPLET Code completion
5135  *
5136  * Code completion involves taking an (incomplete) source file, along with
5137  * knowledge of where the user is actively editing that file, and suggesting
5138  * syntactically- and semantically-valid constructs that the user might want to
5139  * use at that particular point in the source code. These data structures and
5140  * routines provide support for code completion.
5141  *
5142  * @{
5143  */
5144 
5145 /**
5146  * A semantic string that describes a code-completion result.
5147  *
5148  * A semantic string that describes the formatting of a code-completion
5149  * result as a single "template" of text that should be inserted into the
5150  * source buffer when a particular code-completion result is selected.
5151  * Each semantic string is made up of some number of "chunks", each of which
5152  * contains some text along with a description of what that text means, e.g.,
5153  * the name of the entity being referenced, whether the text chunk is part of
5154  * the template, or whether it is a "placeholder" that the user should replace
5155  * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
5156  * description of the different kinds of chunks.
5157  */
5158 typedef void *CXCompletionString;
5159 
5160 /**
5161  * A single result of code completion.
5162  */
5163 typedef struct {
5164   /**
5165    * The kind of entity that this completion refers to.
5166    *
5167    * The cursor kind will be a macro, keyword, or a declaration (one of the
5168    * *Decl cursor kinds), describing the entity that the completion is
5169    * referring to.
5170    *
5171    * \todo In the future, we would like to provide a full cursor, to allow
5172    * the client to extract additional information from declaration.
5173    */
5174   enum CXCursorKind CursorKind;
5175 
5176   /**
5177    * The code-completion string that describes how to insert this
5178    * code-completion result into the editing buffer.
5179    */
5180   CXCompletionString CompletionString;
5181 } CXCompletionResult;
5182 
5183 /**
5184  * Describes a single piece of text within a code-completion string.
5185  *
5186  * Each "chunk" within a code-completion string (\c CXCompletionString) is
5187  * either a piece of text with a specific "kind" that describes how that text
5188  * should be interpreted by the client or is another completion string.
5189  */
5190 enum CXCompletionChunkKind {
5191   /**
5192    * A code-completion string that describes "optional" text that
5193    * could be a part of the template (but is not required).
5194    *
5195    * The Optional chunk is the only kind of chunk that has a code-completion
5196    * string for its representation, which is accessible via
5197    * \c clang_getCompletionChunkCompletionString(). The code-completion string
5198    * describes an additional part of the template that is completely optional.
5199    * For example, optional chunks can be used to describe the placeholders for
5200    * arguments that match up with defaulted function parameters, e.g. given:
5201    *
5202    * \code
5203    * void f(int x, float y = 3.14, double z = 2.71828);
5204    * \endcode
5205    *
5206    * The code-completion string for this function would contain:
5207    *   - a TypedText chunk for "f".
5208    *   - a LeftParen chunk for "(".
5209    *   - a Placeholder chunk for "int x"
5210    *   - an Optional chunk containing the remaining defaulted arguments, e.g.,
5211    *       - a Comma chunk for ","
5212    *       - a Placeholder chunk for "float y"
5213    *       - an Optional chunk containing the last defaulted argument:
5214    *           - a Comma chunk for ","
5215    *           - a Placeholder chunk for "double z"
5216    *   - a RightParen chunk for ")"
5217    *
5218    * There are many ways to handle Optional chunks. Two simple approaches are:
5219    *   - Completely ignore optional chunks, in which case the template for the
5220    *     function "f" would only include the first parameter ("int x").
5221    *   - Fully expand all optional chunks, in which case the template for the
5222    *     function "f" would have all of the parameters.
5223    */
5224   CXCompletionChunk_Optional,
5225   /**
5226    * Text that a user would be expected to type to get this
5227    * code-completion result.
5228    *
5229    * There will be exactly one "typed text" chunk in a semantic string, which
5230    * will typically provide the spelling of a keyword or the name of a
5231    * declaration that could be used at the current code point. Clients are
5232    * expected to filter the code-completion results based on the text in this
5233    * chunk.
5234    */
5235   CXCompletionChunk_TypedText,
5236   /**
5237    * Text that should be inserted as part of a code-completion result.
5238    *
5239    * A "text" chunk represents text that is part of the template to be
5240    * inserted into user code should this particular code-completion result
5241    * be selected.
5242    */
5243   CXCompletionChunk_Text,
5244   /**
5245    * Placeholder text that should be replaced by the user.
5246    *
5247    * A "placeholder" chunk marks a place where the user should insert text
5248    * into the code-completion template. For example, placeholders might mark
5249    * the function parameters for a function declaration, to indicate that the
5250    * user should provide arguments for each of those parameters. The actual
5251    * text in a placeholder is a suggestion for the text to display before
5252    * the user replaces the placeholder with real code.
5253    */
5254   CXCompletionChunk_Placeholder,
5255   /**
5256    * Informative text that should be displayed but never inserted as
5257    * part of the template.
5258    *
5259    * An "informative" chunk contains annotations that can be displayed to
5260    * help the user decide whether a particular code-completion result is the
5261    * right option, but which is not part of the actual template to be inserted
5262    * by code completion.
5263    */
5264   CXCompletionChunk_Informative,
5265   /**
5266    * Text that describes the current parameter when code-completion is
5267    * referring to function call, message send, or template specialization.
5268    *
5269    * A "current parameter" chunk occurs when code-completion is providing
5270    * information about a parameter corresponding to the argument at the
5271    * code-completion point. For example, given a function
5272    *
5273    * \code
5274    * int add(int x, int y);
5275    * \endcode
5276    *
5277    * and the source code \c add(, where the code-completion point is after the
5278    * "(", the code-completion string will contain a "current parameter" chunk
5279    * for "int x", indicating that the current argument will initialize that
5280    * parameter. After typing further, to \c add(17, (where the code-completion
5281    * point is after the ","), the code-completion string will contain a
5282    * "current parameter" chunk to "int y".
5283    */
5284   CXCompletionChunk_CurrentParameter,
5285   /**
5286    * A left parenthesis ('('), used to initiate a function call or
5287    * signal the beginning of a function parameter list.
5288    */
5289   CXCompletionChunk_LeftParen,
5290   /**
5291    * A right parenthesis (')'), used to finish a function call or
5292    * signal the end of a function parameter list.
5293    */
5294   CXCompletionChunk_RightParen,
5295   /**
5296    * A left bracket ('[').
5297    */
5298   CXCompletionChunk_LeftBracket,
5299   /**
5300    * A right bracket (']').
5301    */
5302   CXCompletionChunk_RightBracket,
5303   /**
5304    * A left brace ('{').
5305    */
5306   CXCompletionChunk_LeftBrace,
5307   /**
5308    * A right brace ('}').
5309    */
5310   CXCompletionChunk_RightBrace,
5311   /**
5312    * A left angle bracket ('<').
5313    */
5314   CXCompletionChunk_LeftAngle,
5315   /**
5316    * A right angle bracket ('>').
5317    */
5318   CXCompletionChunk_RightAngle,
5319   /**
5320    * A comma separator (',').
5321    */
5322   CXCompletionChunk_Comma,
5323   /**
5324    * Text that specifies the result type of a given result.
5325    *
5326    * This special kind of informative chunk is not meant to be inserted into
5327    * the text buffer. Rather, it is meant to illustrate the type that an
5328    * expression using the given completion string would have.
5329    */
5330   CXCompletionChunk_ResultType,
5331   /**
5332    * A colon (':').
5333    */
5334   CXCompletionChunk_Colon,
5335   /**
5336    * A semicolon (';').
5337    */
5338   CXCompletionChunk_SemiColon,
5339   /**
5340    * An '=' sign.
5341    */
5342   CXCompletionChunk_Equal,
5343   /**
5344    * Horizontal space (' ').
5345    */
5346   CXCompletionChunk_HorizontalSpace,
5347   /**
5348    * Vertical space ('\\n'), after which it is generally a good idea to
5349    * perform indentation.
5350    */
5351   CXCompletionChunk_VerticalSpace
5352 };
5353 
5354 /**
5355  * Determine the kind of a particular chunk within a completion string.
5356  *
5357  * \param completion_string the completion string to query.
5358  *
5359  * \param chunk_number the 0-based index of the chunk in the completion string.
5360  *
5361  * \returns the kind of the chunk at the index \c chunk_number.
5362  */
5363 CINDEX_LINKAGE enum CXCompletionChunkKind
5364 clang_getCompletionChunkKind(CXCompletionString completion_string,
5365                              unsigned chunk_number);
5366 
5367 /**
5368  * Retrieve the text associated with a particular chunk within a
5369  * completion string.
5370  *
5371  * \param completion_string the completion string to query.
5372  *
5373  * \param chunk_number the 0-based index of the chunk in the completion string.
5374  *
5375  * \returns the text associated with the chunk at index \c chunk_number.
5376  */
5377 CINDEX_LINKAGE CXString clang_getCompletionChunkText(
5378     CXCompletionString completion_string, unsigned chunk_number);
5379 
5380 /**
5381  * Retrieve the completion string associated with a particular chunk
5382  * within a completion string.
5383  *
5384  * \param completion_string the completion string to query.
5385  *
5386  * \param chunk_number the 0-based index of the chunk in the completion string.
5387  *
5388  * \returns the completion string associated with the chunk at index
5389  * \c chunk_number.
5390  */
5391 CINDEX_LINKAGE CXCompletionString clang_getCompletionChunkCompletionString(
5392     CXCompletionString completion_string, unsigned chunk_number);
5393 
5394 /**
5395  * Retrieve the number of chunks in the given code-completion string.
5396  */
5397 CINDEX_LINKAGE unsigned
5398 clang_getNumCompletionChunks(CXCompletionString completion_string);
5399 
5400 /**
5401  * Determine the priority of this code completion.
5402  *
5403  * The priority of a code completion indicates how likely it is that this
5404  * particular completion is the completion that the user will select. The
5405  * priority is selected by various internal heuristics.
5406  *
5407  * \param completion_string The completion string to query.
5408  *
5409  * \returns The priority of this completion string. Smaller values indicate
5410  * higher-priority (more likely) completions.
5411  */
5412 CINDEX_LINKAGE unsigned
5413 clang_getCompletionPriority(CXCompletionString completion_string);
5414 
5415 /**
5416  * Determine the availability of the entity that this code-completion
5417  * string refers to.
5418  *
5419  * \param completion_string The completion string to query.
5420  *
5421  * \returns The availability of the completion string.
5422  */
5423 CINDEX_LINKAGE enum CXAvailabilityKind
5424 clang_getCompletionAvailability(CXCompletionString completion_string);
5425 
5426 /**
5427  * Retrieve the number of annotations associated with the given
5428  * completion string.
5429  *
5430  * \param completion_string the completion string to query.
5431  *
5432  * \returns the number of annotations associated with the given completion
5433  * string.
5434  */
5435 CINDEX_LINKAGE unsigned
5436 clang_getCompletionNumAnnotations(CXCompletionString completion_string);
5437 
5438 /**
5439  * Retrieve the annotation associated with the given completion string.
5440  *
5441  * \param completion_string the completion string to query.
5442  *
5443  * \param annotation_number the 0-based index of the annotation of the
5444  * completion string.
5445  *
5446  * \returns annotation string associated with the completion at index
5447  * \c annotation_number, or a NULL string if that annotation is not available.
5448  */
5449 CINDEX_LINKAGE CXString clang_getCompletionAnnotation(
5450     CXCompletionString completion_string, unsigned annotation_number);
5451 
5452 /**
5453  * Retrieve the parent context of the given completion string.
5454  *
5455  * The parent context of a completion string is the semantic parent of
5456  * the declaration (if any) that the code completion represents. For example,
5457  * a code completion for an Objective-C method would have the method's class
5458  * or protocol as its context.
5459  *
5460  * \param completion_string The code completion string whose parent is
5461  * being queried.
5462  *
5463  * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL.
5464  *
5465  * \returns The name of the completion parent, e.g., "NSObject" if
5466  * the completion string represents a method in the NSObject class.
5467  */
5468 CINDEX_LINKAGE CXString clang_getCompletionParent(
5469     CXCompletionString completion_string, enum CXCursorKind *kind);
5470 
5471 /**
5472  * Retrieve the brief documentation comment attached to the declaration
5473  * that corresponds to the given completion string.
5474  */
5475 CINDEX_LINKAGE CXString
5476 clang_getCompletionBriefComment(CXCompletionString completion_string);
5477 
5478 /**
5479  * Retrieve a completion string for an arbitrary declaration or macro
5480  * definition cursor.
5481  *
5482  * \param cursor The cursor to query.
5483  *
5484  * \returns A non-context-sensitive completion string for declaration and macro
5485  * definition cursors, or NULL for other kinds of cursors.
5486  */
5487 CINDEX_LINKAGE CXCompletionString
5488 clang_getCursorCompletionString(CXCursor cursor);
5489 
5490 /**
5491  * Contains the results of code-completion.
5492  *
5493  * This data structure contains the results of code completion, as
5494  * produced by \c clang_codeCompleteAt(). Its contents must be freed by
5495  * \c clang_disposeCodeCompleteResults.
5496  */
5497 typedef struct {
5498   /**
5499    * The code-completion results.
5500    */
5501   CXCompletionResult *Results;
5502 
5503   /**
5504    * The number of code-completion results stored in the
5505    * \c Results array.
5506    */
5507   unsigned NumResults;
5508 } CXCodeCompleteResults;
5509 
5510 /**
5511  * Retrieve the number of fix-its for the given completion index.
5512  *
5513  * Calling this makes sense only if CXCodeComplete_IncludeCompletionsWithFixIts
5514  * option was set.
5515  *
5516  * \param results The structure keeping all completion results
5517  *
5518  * \param completion_index The index of the completion
5519  *
5520  * \return The number of fix-its which must be applied before the completion at
5521  * completion_index can be applied
5522  */
5523 CINDEX_LINKAGE unsigned
5524 clang_getCompletionNumFixIts(CXCodeCompleteResults *results,
5525                              unsigned completion_index);
5526 
5527 /**
5528  * Fix-its that *must* be applied before inserting the text for the
5529  * corresponding completion.
5530  *
5531  * By default, clang_codeCompleteAt() only returns completions with empty
5532  * fix-its. Extra completions with non-empty fix-its should be explicitly
5533  * requested by setting CXCodeComplete_IncludeCompletionsWithFixIts.
5534  *
5535  * For the clients to be able to compute position of the cursor after applying
5536  * fix-its, the following conditions are guaranteed to hold for
5537  * replacement_range of the stored fix-its:
5538  *  - Ranges in the fix-its are guaranteed to never contain the completion
5539  *  point (or identifier under completion point, if any) inside them, except
5540  *  at the start or at the end of the range.
5541  *  - If a fix-it range starts or ends with completion point (or starts or
5542  *  ends after the identifier under completion point), it will contain at
5543  *  least one character. It allows to unambiguously recompute completion
5544  *  point after applying the fix-it.
5545  *
5546  * The intuition is that provided fix-its change code around the identifier we
5547  * complete, but are not allowed to touch the identifier itself or the
5548  * completion point. One example of completions with corrections are the ones
5549  * replacing '.' with '->' and vice versa:
5550  *
5551  * std::unique_ptr<std::vector<int>> vec_ptr;
5552  * In 'vec_ptr.^', one of the completions is 'push_back', it requires
5553  * replacing '.' with '->'.
5554  * In 'vec_ptr->^', one of the completions is 'release', it requires
5555  * replacing '->' with '.'.
5556  *
5557  * \param results The structure keeping all completion results
5558  *
5559  * \param completion_index The index of the completion
5560  *
5561  * \param fixit_index The index of the fix-it for the completion at
5562  * completion_index
5563  *
5564  * \param replacement_range The fix-it range that must be replaced before the
5565  * completion at completion_index can be applied
5566  *
5567  * \returns The fix-it string that must replace the code at replacement_range
5568  * before the completion at completion_index can be applied
5569  */
5570 CINDEX_LINKAGE CXString clang_getCompletionFixIt(
5571     CXCodeCompleteResults *results, unsigned completion_index,
5572     unsigned fixit_index, CXSourceRange *replacement_range);
5573 
5574 /**
5575  * Flags that can be passed to \c clang_codeCompleteAt() to
5576  * modify its behavior.
5577  *
5578  * The enumerators in this enumeration can be bitwise-OR'd together to
5579  * provide multiple options to \c clang_codeCompleteAt().
5580  */
5581 enum CXCodeComplete_Flags {
5582   /**
5583    * Whether to include macros within the set of code
5584    * completions returned.
5585    */
5586   CXCodeComplete_IncludeMacros = 0x01,
5587 
5588   /**
5589    * Whether to include code patterns for language constructs
5590    * within the set of code completions, e.g., for loops.
5591    */
5592   CXCodeComplete_IncludeCodePatterns = 0x02,
5593 
5594   /**
5595    * Whether to include brief documentation within the set of code
5596    * completions returned.
5597    */
5598   CXCodeComplete_IncludeBriefComments = 0x04,
5599 
5600   /**
5601    * Whether to speed up completion by omitting top- or namespace-level entities
5602    * defined in the preamble. There's no guarantee any particular entity is
5603    * omitted. This may be useful if the headers are indexed externally.
5604    */
5605   CXCodeComplete_SkipPreamble = 0x08,
5606 
5607   /**
5608    * Whether to include completions with small
5609    * fix-its, e.g. change '.' to '->' on member access, etc.
5610    */
5611   CXCodeComplete_IncludeCompletionsWithFixIts = 0x10
5612 };
5613 
5614 /**
5615  * Bits that represent the context under which completion is occurring.
5616  *
5617  * The enumerators in this enumeration may be bitwise-OR'd together if multiple
5618  * contexts are occurring simultaneously.
5619  */
5620 enum CXCompletionContext {
5621   /**
5622    * The context for completions is unexposed, as only Clang results
5623    * should be included. (This is equivalent to having no context bits set.)
5624    */
5625   CXCompletionContext_Unexposed = 0,
5626 
5627   /**
5628    * Completions for any possible type should be included in the results.
5629    */
5630   CXCompletionContext_AnyType = 1 << 0,
5631 
5632   /**
5633    * Completions for any possible value (variables, function calls, etc.)
5634    * should be included in the results.
5635    */
5636   CXCompletionContext_AnyValue = 1 << 1,
5637   /**
5638    * Completions for values that resolve to an Objective-C object should
5639    * be included in the results.
5640    */
5641   CXCompletionContext_ObjCObjectValue = 1 << 2,
5642   /**
5643    * Completions for values that resolve to an Objective-C selector
5644    * should be included in the results.
5645    */
5646   CXCompletionContext_ObjCSelectorValue = 1 << 3,
5647   /**
5648    * Completions for values that resolve to a C++ class type should be
5649    * included in the results.
5650    */
5651   CXCompletionContext_CXXClassTypeValue = 1 << 4,
5652 
5653   /**
5654    * Completions for fields of the member being accessed using the dot
5655    * operator should be included in the results.
5656    */
5657   CXCompletionContext_DotMemberAccess = 1 << 5,
5658   /**
5659    * Completions for fields of the member being accessed using the arrow
5660    * operator should be included in the results.
5661    */
5662   CXCompletionContext_ArrowMemberAccess = 1 << 6,
5663   /**
5664    * Completions for properties of the Objective-C object being accessed
5665    * using the dot operator should be included in the results.
5666    */
5667   CXCompletionContext_ObjCPropertyAccess = 1 << 7,
5668 
5669   /**
5670    * Completions for enum tags should be included in the results.
5671    */
5672   CXCompletionContext_EnumTag = 1 << 8,
5673   /**
5674    * Completions for union tags should be included in the results.
5675    */
5676   CXCompletionContext_UnionTag = 1 << 9,
5677   /**
5678    * Completions for struct tags should be included in the results.
5679    */
5680   CXCompletionContext_StructTag = 1 << 10,
5681 
5682   /**
5683    * Completions for C++ class names should be included in the results.
5684    */
5685   CXCompletionContext_ClassTag = 1 << 11,
5686   /**
5687    * Completions for C++ namespaces and namespace aliases should be
5688    * included in the results.
5689    */
5690   CXCompletionContext_Namespace = 1 << 12,
5691   /**
5692    * Completions for C++ nested name specifiers should be included in
5693    * the results.
5694    */
5695   CXCompletionContext_NestedNameSpecifier = 1 << 13,
5696 
5697   /**
5698    * Completions for Objective-C interfaces (classes) should be included
5699    * in the results.
5700    */
5701   CXCompletionContext_ObjCInterface = 1 << 14,
5702   /**
5703    * Completions for Objective-C protocols should be included in
5704    * the results.
5705    */
5706   CXCompletionContext_ObjCProtocol = 1 << 15,
5707   /**
5708    * Completions for Objective-C categories should be included in
5709    * the results.
5710    */
5711   CXCompletionContext_ObjCCategory = 1 << 16,
5712   /**
5713    * Completions for Objective-C instance messages should be included
5714    * in the results.
5715    */
5716   CXCompletionContext_ObjCInstanceMessage = 1 << 17,
5717   /**
5718    * Completions for Objective-C class messages should be included in
5719    * the results.
5720    */
5721   CXCompletionContext_ObjCClassMessage = 1 << 18,
5722   /**
5723    * Completions for Objective-C selector names should be included in
5724    * the results.
5725    */
5726   CXCompletionContext_ObjCSelectorName = 1 << 19,
5727 
5728   /**
5729    * Completions for preprocessor macro names should be included in
5730    * the results.
5731    */
5732   CXCompletionContext_MacroName = 1 << 20,
5733 
5734   /**
5735    * Natural language completions should be included in the results.
5736    */
5737   CXCompletionContext_NaturalLanguage = 1 << 21,
5738 
5739   /**
5740    * #include file completions should be included in the results.
5741    */
5742   CXCompletionContext_IncludedFile = 1 << 22,
5743 
5744   /**
5745    * The current context is unknown, so set all contexts.
5746    */
5747   CXCompletionContext_Unknown = ((1 << 23) - 1)
5748 };
5749 
5750 /**
5751  * Returns a default set of code-completion options that can be
5752  * passed to\c clang_codeCompleteAt().
5753  */
5754 CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void);
5755 
5756 /**
5757  * Perform code completion at a given location in a translation unit.
5758  *
5759  * This function performs code completion at a particular file, line, and
5760  * column within source code, providing results that suggest potential
5761  * code snippets based on the context of the completion. The basic model
5762  * for code completion is that Clang will parse a complete source file,
5763  * performing syntax checking up to the location where code-completion has
5764  * been requested. At that point, a special code-completion token is passed
5765  * to the parser, which recognizes this token and determines, based on the
5766  * current location in the C/Objective-C/C++ grammar and the state of
5767  * semantic analysis, what completions to provide. These completions are
5768  * returned via a new \c CXCodeCompleteResults structure.
5769  *
5770  * Code completion itself is meant to be triggered by the client when the
5771  * user types punctuation characters or whitespace, at which point the
5772  * code-completion location will coincide with the cursor. For example, if \c p
5773  * is a pointer, code-completion might be triggered after the "-" and then
5774  * after the ">" in \c p->. When the code-completion location is after the ">",
5775  * the completion results will provide, e.g., the members of the struct that
5776  * "p" points to. The client is responsible for placing the cursor at the
5777  * beginning of the token currently being typed, then filtering the results
5778  * based on the contents of the token. For example, when code-completing for
5779  * the expression \c p->get, the client should provide the location just after
5780  * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
5781  * client can filter the results based on the current token text ("get"), only
5782  * showing those results that start with "get". The intent of this interface
5783  * is to separate the relatively high-latency acquisition of code-completion
5784  * results from the filtering of results on a per-character basis, which must
5785  * have a lower latency.
5786  *
5787  * \param TU The translation unit in which code-completion should
5788  * occur. The source files for this translation unit need not be
5789  * completely up-to-date (and the contents of those source files may
5790  * be overridden via \p unsaved_files). Cursors referring into the
5791  * translation unit may be invalidated by this invocation.
5792  *
5793  * \param complete_filename The name of the source file where code
5794  * completion should be performed. This filename may be any file
5795  * included in the translation unit.
5796  *
5797  * \param complete_line The line at which code-completion should occur.
5798  *
5799  * \param complete_column The column at which code-completion should occur.
5800  * Note that the column should point just after the syntactic construct that
5801  * initiated code completion, and not in the middle of a lexical token.
5802  *
5803  * \param unsaved_files the Files that have not yet been saved to disk
5804  * but may be required for parsing or code completion, including the
5805  * contents of those files.  The contents and name of these files (as
5806  * specified by CXUnsavedFile) are copied when necessary, so the
5807  * client only needs to guarantee their validity until the call to
5808  * this function returns.
5809  *
5810  * \param num_unsaved_files The number of unsaved file entries in \p
5811  * unsaved_files.
5812  *
5813  * \param options Extra options that control the behavior of code
5814  * completion, expressed as a bitwise OR of the enumerators of the
5815  * CXCodeComplete_Flags enumeration. The
5816  * \c clang_defaultCodeCompleteOptions() function returns a default set
5817  * of code-completion options.
5818  *
5819  * \returns If successful, a new \c CXCodeCompleteResults structure
5820  * containing code-completion results, which should eventually be
5821  * freed with \c clang_disposeCodeCompleteResults(). If code
5822  * completion fails, returns NULL.
5823  */
5824 CINDEX_LINKAGE
5825 CXCodeCompleteResults *
5826 clang_codeCompleteAt(CXTranslationUnit TU, const char *complete_filename,
5827                      unsigned complete_line, unsigned complete_column,
5828                      struct CXUnsavedFile *unsaved_files,
5829                      unsigned num_unsaved_files, unsigned options);
5830 
5831 /**
5832  * Sort the code-completion results in case-insensitive alphabetical
5833  * order.
5834  *
5835  * \param Results The set of results to sort.
5836  * \param NumResults The number of results in \p Results.
5837  */
5838 CINDEX_LINKAGE
5839 void clang_sortCodeCompletionResults(CXCompletionResult *Results,
5840                                      unsigned NumResults);
5841 
5842 /**
5843  * Free the given set of code-completion results.
5844  */
5845 CINDEX_LINKAGE
5846 void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results);
5847 
5848 /**
5849  * Determine the number of diagnostics produced prior to the
5850  * location where code completion was performed.
5851  */
5852 CINDEX_LINKAGE
5853 unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results);
5854 
5855 /**
5856  * Retrieve a diagnostic associated with the given code completion.
5857  *
5858  * \param Results the code completion results to query.
5859  * \param Index the zero-based diagnostic number to retrieve.
5860  *
5861  * \returns the requested diagnostic. This diagnostic must be freed
5862  * via a call to \c clang_disposeDiagnostic().
5863  */
5864 CINDEX_LINKAGE
5865 CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results,
5866                                              unsigned Index);
5867 
5868 /**
5869  * Determines what completions are appropriate for the context
5870  * the given code completion.
5871  *
5872  * \param Results the code completion results to query
5873  *
5874  * \returns the kinds of completions that are appropriate for use
5875  * along with the given code completion results.
5876  */
5877 CINDEX_LINKAGE
5878 unsigned long long
5879 clang_codeCompleteGetContexts(CXCodeCompleteResults *Results);
5880 
5881 /**
5882  * Returns the cursor kind for the container for the current code
5883  * completion context. The container is only guaranteed to be set for
5884  * contexts where a container exists (i.e. member accesses or Objective-C
5885  * message sends); if there is not a container, this function will return
5886  * CXCursor_InvalidCode.
5887  *
5888  * \param Results the code completion results to query
5889  *
5890  * \param IsIncomplete on return, this value will be false if Clang has complete
5891  * information about the container. If Clang does not have complete
5892  * information, this value will be true.
5893  *
5894  * \returns the container kind, or CXCursor_InvalidCode if there is not a
5895  * container
5896  */
5897 CINDEX_LINKAGE
5898 enum CXCursorKind
5899 clang_codeCompleteGetContainerKind(CXCodeCompleteResults *Results,
5900                                    unsigned *IsIncomplete);
5901 
5902 /**
5903  * Returns the USR for the container for the current code completion
5904  * context. If there is not a container for the current context, this
5905  * function will return the empty string.
5906  *
5907  * \param Results the code completion results to query
5908  *
5909  * \returns the USR for the container
5910  */
5911 CINDEX_LINKAGE
5912 CXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results);
5913 
5914 /**
5915  * Returns the currently-entered selector for an Objective-C message
5916  * send, formatted like "initWithFoo:bar:". Only guaranteed to return a
5917  * non-empty string for CXCompletionContext_ObjCInstanceMessage and
5918  * CXCompletionContext_ObjCClassMessage.
5919  *
5920  * \param Results the code completion results to query
5921  *
5922  * \returns the selector (or partial selector) that has been entered thus far
5923  * for an Objective-C message send.
5924  */
5925 CINDEX_LINKAGE
5926 CXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results);
5927 
5928 /**
5929  * @}
5930  */
5931 
5932 /**
5933  * \defgroup CINDEX_MISC Miscellaneous utility functions
5934  *
5935  * @{
5936  */
5937 
5938 /**
5939  * Return a version string, suitable for showing to a user, but not
5940  *        intended to be parsed (the format is not guaranteed to be stable).
5941  */
5942 CINDEX_LINKAGE CXString clang_getClangVersion(void);
5943 
5944 /**
5945  * Enable/disable crash recovery.
5946  *
5947  * \param isEnabled Flag to indicate if crash recovery is enabled.  A non-zero
5948  *        value enables crash recovery, while 0 disables it.
5949  */
5950 CINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled);
5951 
5952 /**
5953  * Visitor invoked for each file in a translation unit
5954  *        (used with clang_getInclusions()).
5955  *
5956  * This visitor function will be invoked by clang_getInclusions() for each
5957  * file included (either at the top-level or by \#include directives) within
5958  * a translation unit.  The first argument is the file being included, and
5959  * the second and third arguments provide the inclusion stack.  The
5960  * array is sorted in order of immediate inclusion.  For example,
5961  * the first element refers to the location that included 'included_file'.
5962  */
5963 typedef void (*CXInclusionVisitor)(CXFile included_file,
5964                                    CXSourceLocation *inclusion_stack,
5965                                    unsigned include_len,
5966                                    CXClientData client_data);
5967 
5968 /**
5969  * Visit the set of preprocessor inclusions in a translation unit.
5970  *   The visitor function is called with the provided data for every included
5971  *   file.  This does not include headers included by the PCH file (unless one
5972  *   is inspecting the inclusions in the PCH file itself).
5973  */
5974 CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
5975                                         CXInclusionVisitor visitor,
5976                                         CXClientData client_data);
5977 
5978 typedef enum {
5979   CXEval_Int = 1,
5980   CXEval_Float = 2,
5981   CXEval_ObjCStrLiteral = 3,
5982   CXEval_StrLiteral = 4,
5983   CXEval_CFStr = 5,
5984   CXEval_Other = 6,
5985 
5986   CXEval_UnExposed = 0
5987 
5988 } CXEvalResultKind;
5989 
5990 /**
5991  * Evaluation result of a cursor
5992  */
5993 typedef void *CXEvalResult;
5994 
5995 /**
5996  * If cursor is a statement declaration tries to evaluate the
5997  * statement and if its variable, tries to evaluate its initializer,
5998  * into its corresponding type.
5999  * If it's an expression, tries to evaluate the expression.
6000  */
6001 CINDEX_LINKAGE CXEvalResult clang_Cursor_Evaluate(CXCursor C);
6002 
6003 /**
6004  * Returns the kind of the evaluated result.
6005  */
6006 CINDEX_LINKAGE CXEvalResultKind clang_EvalResult_getKind(CXEvalResult E);
6007 
6008 /**
6009  * Returns the evaluation result as integer if the
6010  * kind is Int.
6011  */
6012 CINDEX_LINKAGE int clang_EvalResult_getAsInt(CXEvalResult E);
6013 
6014 /**
6015  * Returns the evaluation result as a long long integer if the
6016  * kind is Int. This prevents overflows that may happen if the result is
6017  * returned with clang_EvalResult_getAsInt.
6018  */
6019 CINDEX_LINKAGE long long clang_EvalResult_getAsLongLong(CXEvalResult E);
6020 
6021 /**
6022  * Returns a non-zero value if the kind is Int and the evaluation
6023  * result resulted in an unsigned integer.
6024  */
6025 CINDEX_LINKAGE unsigned clang_EvalResult_isUnsignedInt(CXEvalResult E);
6026 
6027 /**
6028  * Returns the evaluation result as an unsigned integer if
6029  * the kind is Int and clang_EvalResult_isUnsignedInt is non-zero.
6030  */
6031 CINDEX_LINKAGE unsigned long long
6032 clang_EvalResult_getAsUnsigned(CXEvalResult E);
6033 
6034 /**
6035  * Returns the evaluation result as double if the
6036  * kind is double.
6037  */
6038 CINDEX_LINKAGE double clang_EvalResult_getAsDouble(CXEvalResult E);
6039 
6040 /**
6041  * Returns the evaluation result as a constant string if the
6042  * kind is other than Int or float. User must not free this pointer,
6043  * instead call clang_EvalResult_dispose on the CXEvalResult returned
6044  * by clang_Cursor_Evaluate.
6045  */
6046 CINDEX_LINKAGE const char *clang_EvalResult_getAsStr(CXEvalResult E);
6047 
6048 /**
6049  * Disposes the created Eval memory.
6050  */
6051 CINDEX_LINKAGE void clang_EvalResult_dispose(CXEvalResult E);
6052 /**
6053  * @}
6054  */
6055 
6056 /** \defgroup CINDEX_REMAPPING Remapping functions
6057  *
6058  * @{
6059  */
6060 
6061 /**
6062  * A remapping of original source files and their translated files.
6063  */
6064 typedef void *CXRemapping;
6065 
6066 /**
6067  * Retrieve a remapping.
6068  *
6069  * \param path the path that contains metadata about remappings.
6070  *
6071  * \returns the requested remapping. This remapping must be freed
6072  * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred.
6073  */
6074 CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path);
6075 
6076 /**
6077  * Retrieve a remapping.
6078  *
6079  * \param filePaths pointer to an array of file paths containing remapping info.
6080  *
6081  * \param numFiles number of file paths.
6082  *
6083  * \returns the requested remapping. This remapping must be freed
6084  * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred.
6085  */
6086 CINDEX_LINKAGE
6087 CXRemapping clang_getRemappingsFromFileList(const char **filePaths,
6088                                             unsigned numFiles);
6089 
6090 /**
6091  * Determine the number of remappings.
6092  */
6093 CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping);
6094 
6095 /**
6096  * Get the original and the associated filename from the remapping.
6097  *
6098  * \param original If non-NULL, will be set to the original filename.
6099  *
6100  * \param transformed If non-NULL, will be set to the filename that the original
6101  * is associated with.
6102  */
6103 CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index,
6104                                              CXString *original,
6105                                              CXString *transformed);
6106 
6107 /**
6108  * Dispose the remapping.
6109  */
6110 CINDEX_LINKAGE void clang_remap_dispose(CXRemapping);
6111 
6112 /**
6113  * @}
6114  */
6115 
6116 /** \defgroup CINDEX_HIGH Higher level API functions
6117  *
6118  * @{
6119  */
6120 
6121 enum CXVisitorResult { CXVisit_Break, CXVisit_Continue };
6122 
6123 typedef struct CXCursorAndRangeVisitor {
6124   void *context;
6125   enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange);
6126 } CXCursorAndRangeVisitor;
6127 
6128 typedef enum {
6129   /**
6130    * Function returned successfully.
6131    */
6132   CXResult_Success = 0,
6133   /**
6134    * One of the parameters was invalid for the function.
6135    */
6136   CXResult_Invalid = 1,
6137   /**
6138    * The function was terminated by a callback (e.g. it returned
6139    * CXVisit_Break)
6140    */
6141   CXResult_VisitBreak = 2
6142 
6143 } CXResult;
6144 
6145 /**
6146  * Find references of a declaration in a specific file.
6147  *
6148  * \param cursor pointing to a declaration or a reference of one.
6149  *
6150  * \param file to search for references.
6151  *
6152  * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for
6153  * each reference found.
6154  * The CXSourceRange will point inside the file; if the reference is inside
6155  * a macro (and not a macro argument) the CXSourceRange will be invalid.
6156  *
6157  * \returns one of the CXResult enumerators.
6158  */
6159 CINDEX_LINKAGE CXResult clang_findReferencesInFile(
6160     CXCursor cursor, CXFile file, CXCursorAndRangeVisitor visitor);
6161 
6162 /**
6163  * Find #import/#include directives in a specific file.
6164  *
6165  * \param TU translation unit containing the file to query.
6166  *
6167  * \param file to search for #import/#include directives.
6168  *
6169  * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for
6170  * each directive found.
6171  *
6172  * \returns one of the CXResult enumerators.
6173  */
6174 CINDEX_LINKAGE CXResult clang_findIncludesInFile(
6175     CXTranslationUnit TU, CXFile file, CXCursorAndRangeVisitor visitor);
6176 
6177 #ifdef __has_feature
6178 #if __has_feature(blocks)
6179 
6180 typedef enum CXVisitorResult (^CXCursorAndRangeVisitorBlock)(CXCursor,
6181                                                              CXSourceRange);
6182 
6183 CINDEX_LINKAGE
6184 CXResult clang_findReferencesInFileWithBlock(CXCursor, CXFile,
6185                                              CXCursorAndRangeVisitorBlock);
6186 
6187 CINDEX_LINKAGE
6188 CXResult clang_findIncludesInFileWithBlock(CXTranslationUnit, CXFile,
6189                                            CXCursorAndRangeVisitorBlock);
6190 
6191 #endif
6192 #endif
6193 
6194 /**
6195  * The client's data object that is associated with a CXFile.
6196  */
6197 typedef void *CXIdxClientFile;
6198 
6199 /**
6200  * The client's data object that is associated with a semantic entity.
6201  */
6202 typedef void *CXIdxClientEntity;
6203 
6204 /**
6205  * The client's data object that is associated with a semantic container
6206  * of entities.
6207  */
6208 typedef void *CXIdxClientContainer;
6209 
6210 /**
6211  * The client's data object that is associated with an AST file (PCH
6212  * or module).
6213  */
6214 typedef void *CXIdxClientASTFile;
6215 
6216 /**
6217  * Source location passed to index callbacks.
6218  */
6219 typedef struct {
6220   void *ptr_data[2];
6221   unsigned int_data;
6222 } CXIdxLoc;
6223 
6224 /**
6225  * Data for ppIncludedFile callback.
6226  */
6227 typedef struct {
6228   /**
6229    * Location of '#' in the \#include/\#import directive.
6230    */
6231   CXIdxLoc hashLoc;
6232   /**
6233    * Filename as written in the \#include/\#import directive.
6234    */
6235   const char *filename;
6236   /**
6237    * The actual file that the \#include/\#import directive resolved to.
6238    */
6239   CXFile file;
6240   int isImport;
6241   int isAngled;
6242   /**
6243    * Non-zero if the directive was automatically turned into a module
6244    * import.
6245    */
6246   int isModuleImport;
6247 } CXIdxIncludedFileInfo;
6248 
6249 /**
6250  * Data for IndexerCallbacks#importedASTFile.
6251  */
6252 typedef struct {
6253   /**
6254    * Top level AST file containing the imported PCH, module or submodule.
6255    */
6256   CXFile file;
6257   /**
6258    * The imported module or NULL if the AST file is a PCH.
6259    */
6260   CXModule module;
6261   /**
6262    * Location where the file is imported. Applicable only for modules.
6263    */
6264   CXIdxLoc loc;
6265   /**
6266    * Non-zero if an inclusion directive was automatically turned into
6267    * a module import. Applicable only for modules.
6268    */
6269   int isImplicit;
6270 
6271 } CXIdxImportedASTFileInfo;
6272 
6273 typedef enum {
6274   CXIdxEntity_Unexposed = 0,
6275   CXIdxEntity_Typedef = 1,
6276   CXIdxEntity_Function = 2,
6277   CXIdxEntity_Variable = 3,
6278   CXIdxEntity_Field = 4,
6279   CXIdxEntity_EnumConstant = 5,
6280 
6281   CXIdxEntity_ObjCClass = 6,
6282   CXIdxEntity_ObjCProtocol = 7,
6283   CXIdxEntity_ObjCCategory = 8,
6284 
6285   CXIdxEntity_ObjCInstanceMethod = 9,
6286   CXIdxEntity_ObjCClassMethod = 10,
6287   CXIdxEntity_ObjCProperty = 11,
6288   CXIdxEntity_ObjCIvar = 12,
6289 
6290   CXIdxEntity_Enum = 13,
6291   CXIdxEntity_Struct = 14,
6292   CXIdxEntity_Union = 15,
6293 
6294   CXIdxEntity_CXXClass = 16,
6295   CXIdxEntity_CXXNamespace = 17,
6296   CXIdxEntity_CXXNamespaceAlias = 18,
6297   CXIdxEntity_CXXStaticVariable = 19,
6298   CXIdxEntity_CXXStaticMethod = 20,
6299   CXIdxEntity_CXXInstanceMethod = 21,
6300   CXIdxEntity_CXXConstructor = 22,
6301   CXIdxEntity_CXXDestructor = 23,
6302   CXIdxEntity_CXXConversionFunction = 24,
6303   CXIdxEntity_CXXTypeAlias = 25,
6304   CXIdxEntity_CXXInterface = 26
6305 
6306 } CXIdxEntityKind;
6307 
6308 typedef enum {
6309   CXIdxEntityLang_None = 0,
6310   CXIdxEntityLang_C = 1,
6311   CXIdxEntityLang_ObjC = 2,
6312   CXIdxEntityLang_CXX = 3,
6313   CXIdxEntityLang_Swift = 4
6314 } CXIdxEntityLanguage;
6315 
6316 /**
6317  * Extra C++ template information for an entity. This can apply to:
6318  * CXIdxEntity_Function
6319  * CXIdxEntity_CXXClass
6320  * CXIdxEntity_CXXStaticMethod
6321  * CXIdxEntity_CXXInstanceMethod
6322  * CXIdxEntity_CXXConstructor
6323  * CXIdxEntity_CXXConversionFunction
6324  * CXIdxEntity_CXXTypeAlias
6325  */
6326 typedef enum {
6327   CXIdxEntity_NonTemplate = 0,
6328   CXIdxEntity_Template = 1,
6329   CXIdxEntity_TemplatePartialSpecialization = 2,
6330   CXIdxEntity_TemplateSpecialization = 3
6331 } CXIdxEntityCXXTemplateKind;
6332 
6333 typedef enum {
6334   CXIdxAttr_Unexposed = 0,
6335   CXIdxAttr_IBAction = 1,
6336   CXIdxAttr_IBOutlet = 2,
6337   CXIdxAttr_IBOutletCollection = 3
6338 } CXIdxAttrKind;
6339 
6340 typedef struct {
6341   CXIdxAttrKind kind;
6342   CXCursor cursor;
6343   CXIdxLoc loc;
6344 } CXIdxAttrInfo;
6345 
6346 typedef struct {
6347   CXIdxEntityKind kind;
6348   CXIdxEntityCXXTemplateKind templateKind;
6349   CXIdxEntityLanguage lang;
6350   const char *name;
6351   const char *USR;
6352   CXCursor cursor;
6353   const CXIdxAttrInfo *const *attributes;
6354   unsigned numAttributes;
6355 } CXIdxEntityInfo;
6356 
6357 typedef struct {
6358   CXCursor cursor;
6359 } CXIdxContainerInfo;
6360 
6361 typedef struct {
6362   const CXIdxAttrInfo *attrInfo;
6363   const CXIdxEntityInfo *objcClass;
6364   CXCursor classCursor;
6365   CXIdxLoc classLoc;
6366 } CXIdxIBOutletCollectionAttrInfo;
6367 
6368 typedef enum { CXIdxDeclFlag_Skipped = 0x1 } CXIdxDeclInfoFlags;
6369 
6370 typedef struct {
6371   const CXIdxEntityInfo *entityInfo;
6372   CXCursor cursor;
6373   CXIdxLoc loc;
6374   const CXIdxContainerInfo *semanticContainer;
6375   /**
6376    * Generally same as #semanticContainer but can be different in
6377    * cases like out-of-line C++ member functions.
6378    */
6379   const CXIdxContainerInfo *lexicalContainer;
6380   int isRedeclaration;
6381   int isDefinition;
6382   int isContainer;
6383   const CXIdxContainerInfo *declAsContainer;
6384   /**
6385    * Whether the declaration exists in code or was created implicitly
6386    * by the compiler, e.g. implicit Objective-C methods for properties.
6387    */
6388   int isImplicit;
6389   const CXIdxAttrInfo *const *attributes;
6390   unsigned numAttributes;
6391 
6392   unsigned flags;
6393 
6394 } CXIdxDeclInfo;
6395 
6396 typedef enum {
6397   CXIdxObjCContainer_ForwardRef = 0,
6398   CXIdxObjCContainer_Interface = 1,
6399   CXIdxObjCContainer_Implementation = 2
6400 } CXIdxObjCContainerKind;
6401 
6402 typedef struct {
6403   const CXIdxDeclInfo *declInfo;
6404   CXIdxObjCContainerKind kind;
6405 } CXIdxObjCContainerDeclInfo;
6406 
6407 typedef struct {
6408   const CXIdxEntityInfo *base;
6409   CXCursor cursor;
6410   CXIdxLoc loc;
6411 } CXIdxBaseClassInfo;
6412 
6413 typedef struct {
6414   const CXIdxEntityInfo *protocol;
6415   CXCursor cursor;
6416   CXIdxLoc loc;
6417 } CXIdxObjCProtocolRefInfo;
6418 
6419 typedef struct {
6420   const CXIdxObjCProtocolRefInfo *const *protocols;
6421   unsigned numProtocols;
6422 } CXIdxObjCProtocolRefListInfo;
6423 
6424 typedef struct {
6425   const CXIdxObjCContainerDeclInfo *containerInfo;
6426   const CXIdxBaseClassInfo *superInfo;
6427   const CXIdxObjCProtocolRefListInfo *protocols;
6428 } CXIdxObjCInterfaceDeclInfo;
6429 
6430 typedef struct {
6431   const CXIdxObjCContainerDeclInfo *containerInfo;
6432   const CXIdxEntityInfo *objcClass;
6433   CXCursor classCursor;
6434   CXIdxLoc classLoc;
6435   const CXIdxObjCProtocolRefListInfo *protocols;
6436 } CXIdxObjCCategoryDeclInfo;
6437 
6438 typedef struct {
6439   const CXIdxDeclInfo *declInfo;
6440   const CXIdxEntityInfo *getter;
6441   const CXIdxEntityInfo *setter;
6442 } CXIdxObjCPropertyDeclInfo;
6443 
6444 typedef struct {
6445   const CXIdxDeclInfo *declInfo;
6446   const CXIdxBaseClassInfo *const *bases;
6447   unsigned numBases;
6448 } CXIdxCXXClassDeclInfo;
6449 
6450 /**
6451  * Data for IndexerCallbacks#indexEntityReference.
6452  *
6453  * This may be deprecated in a future version as this duplicates
6454  * the \c CXSymbolRole_Implicit bit in \c CXSymbolRole.
6455  */
6456 typedef enum {
6457   /**
6458    * The entity is referenced directly in user's code.
6459    */
6460   CXIdxEntityRef_Direct = 1,
6461   /**
6462    * An implicit reference, e.g. a reference of an Objective-C method
6463    * via the dot syntax.
6464    */
6465   CXIdxEntityRef_Implicit = 2
6466 } CXIdxEntityRefKind;
6467 
6468 /**
6469  * Roles that are attributed to symbol occurrences.
6470  *
6471  * Internal: this currently mirrors low 9 bits of clang::index::SymbolRole with
6472  * higher bits zeroed. These high bits may be exposed in the future.
6473  */
6474 typedef enum {
6475   CXSymbolRole_None = 0,
6476   CXSymbolRole_Declaration = 1 << 0,
6477   CXSymbolRole_Definition = 1 << 1,
6478   CXSymbolRole_Reference = 1 << 2,
6479   CXSymbolRole_Read = 1 << 3,
6480   CXSymbolRole_Write = 1 << 4,
6481   CXSymbolRole_Call = 1 << 5,
6482   CXSymbolRole_Dynamic = 1 << 6,
6483   CXSymbolRole_AddressOf = 1 << 7,
6484   CXSymbolRole_Implicit = 1 << 8
6485 } CXSymbolRole;
6486 
6487 /**
6488  * Data for IndexerCallbacks#indexEntityReference.
6489  */
6490 typedef struct {
6491   CXIdxEntityRefKind kind;
6492   /**
6493    * Reference cursor.
6494    */
6495   CXCursor cursor;
6496   CXIdxLoc loc;
6497   /**
6498    * The entity that gets referenced.
6499    */
6500   const CXIdxEntityInfo *referencedEntity;
6501   /**
6502    * Immediate "parent" of the reference. For example:
6503    *
6504    * \code
6505    * Foo *var;
6506    * \endcode
6507    *
6508    * The parent of reference of type 'Foo' is the variable 'var'.
6509    * For references inside statement bodies of functions/methods,
6510    * the parentEntity will be the function/method.
6511    */
6512   const CXIdxEntityInfo *parentEntity;
6513   /**
6514    * Lexical container context of the reference.
6515    */
6516   const CXIdxContainerInfo *container;
6517   /**
6518    * Sets of symbol roles of the reference.
6519    */
6520   CXSymbolRole role;
6521 } CXIdxEntityRefInfo;
6522 
6523 /**
6524  * A group of callbacks used by #clang_indexSourceFile and
6525  * #clang_indexTranslationUnit.
6526  */
6527 typedef struct {
6528   /**
6529    * Called periodically to check whether indexing should be aborted.
6530    * Should return 0 to continue, and non-zero to abort.
6531    */
6532   int (*abortQuery)(CXClientData client_data, void *reserved);
6533 
6534   /**
6535    * Called at the end of indexing; passes the complete diagnostic set.
6536    */
6537   void (*diagnostic)(CXClientData client_data, CXDiagnosticSet, void *reserved);
6538 
6539   CXIdxClientFile (*enteredMainFile)(CXClientData client_data, CXFile mainFile,
6540                                      void *reserved);
6541 
6542   /**
6543    * Called when a file gets \#included/\#imported.
6544    */
6545   CXIdxClientFile (*ppIncludedFile)(CXClientData client_data,
6546                                     const CXIdxIncludedFileInfo *);
6547 
6548   /**
6549    * Called when a AST file (PCH or module) gets imported.
6550    *
6551    * AST files will not get indexed (there will not be callbacks to index all
6552    * the entities in an AST file). The recommended action is that, if the AST
6553    * file is not already indexed, to initiate a new indexing job specific to
6554    * the AST file.
6555    */
6556   CXIdxClientASTFile (*importedASTFile)(CXClientData client_data,
6557                                         const CXIdxImportedASTFileInfo *);
6558 
6559   /**
6560    * Called at the beginning of indexing a translation unit.
6561    */
6562   CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data,
6563                                                  void *reserved);
6564 
6565   void (*indexDeclaration)(CXClientData client_data, const CXIdxDeclInfo *);
6566 
6567   /**
6568    * Called to index a reference of an entity.
6569    */
6570   void (*indexEntityReference)(CXClientData client_data,
6571                                const CXIdxEntityRefInfo *);
6572 
6573 } IndexerCallbacks;
6574 
6575 CINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind);
6576 CINDEX_LINKAGE const CXIdxObjCContainerDeclInfo *
6577 clang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *);
6578 
6579 CINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo *
6580 clang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *);
6581 
6582 CINDEX_LINKAGE
6583 const CXIdxObjCCategoryDeclInfo *
6584 clang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *);
6585 
6586 CINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo *
6587 clang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *);
6588 
6589 CINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo *
6590 clang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *);
6591 
6592 CINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo *
6593 clang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *);
6594 
6595 CINDEX_LINKAGE const CXIdxCXXClassDeclInfo *
6596 clang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *);
6597 
6598 /**
6599  * For retrieving a custom CXIdxClientContainer attached to a
6600  * container.
6601  */
6602 CINDEX_LINKAGE CXIdxClientContainer
6603 clang_index_getClientContainer(const CXIdxContainerInfo *);
6604 
6605 /**
6606  * For setting a custom CXIdxClientContainer attached to a
6607  * container.
6608  */
6609 CINDEX_LINKAGE void clang_index_setClientContainer(const CXIdxContainerInfo *,
6610                                                    CXIdxClientContainer);
6611 
6612 /**
6613  * For retrieving a custom CXIdxClientEntity attached to an entity.
6614  */
6615 CINDEX_LINKAGE CXIdxClientEntity
6616 clang_index_getClientEntity(const CXIdxEntityInfo *);
6617 
6618 /**
6619  * For setting a custom CXIdxClientEntity attached to an entity.
6620  */
6621 CINDEX_LINKAGE void clang_index_setClientEntity(const CXIdxEntityInfo *,
6622                                                 CXIdxClientEntity);
6623 
6624 /**
6625  * An indexing action/session, to be applied to one or multiple
6626  * translation units.
6627  */
6628 typedef void *CXIndexAction;
6629 
6630 /**
6631  * An indexing action/session, to be applied to one or multiple
6632  * translation units.
6633  *
6634  * \param CIdx The index object with which the index action will be associated.
6635  */
6636 CINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx);
6637 
6638 /**
6639  * Destroy the given index action.
6640  *
6641  * The index action must not be destroyed until all of the translation units
6642  * created within that index action have been destroyed.
6643  */
6644 CINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction);
6645 
6646 typedef enum {
6647   /**
6648    * Used to indicate that no special indexing options are needed.
6649    */
6650   CXIndexOpt_None = 0x0,
6651 
6652   /**
6653    * Used to indicate that IndexerCallbacks#indexEntityReference should
6654    * be invoked for only one reference of an entity per source file that does
6655    * not also include a declaration/definition of the entity.
6656    */
6657   CXIndexOpt_SuppressRedundantRefs = 0x1,
6658 
6659   /**
6660    * Function-local symbols should be indexed. If this is not set
6661    * function-local symbols will be ignored.
6662    */
6663   CXIndexOpt_IndexFunctionLocalSymbols = 0x2,
6664 
6665   /**
6666    * Implicit function/class template instantiations should be indexed.
6667    * If this is not set, implicit instantiations will be ignored.
6668    */
6669   CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4,
6670 
6671   /**
6672    * Suppress all compiler warnings when parsing for indexing.
6673    */
6674   CXIndexOpt_SuppressWarnings = 0x8,
6675 
6676   /**
6677    * Skip a function/method body that was already parsed during an
6678    * indexing session associated with a \c CXIndexAction object.
6679    * Bodies in system headers are always skipped.
6680    */
6681   CXIndexOpt_SkipParsedBodiesInSession = 0x10
6682 
6683 } CXIndexOptFlags;
6684 
6685 /**
6686  * Index the given source file and the translation unit corresponding
6687  * to that file via callbacks implemented through #IndexerCallbacks.
6688  *
6689  * \param client_data pointer data supplied by the client, which will
6690  * be passed to the invoked callbacks.
6691  *
6692  * \param index_callbacks Pointer to indexing callbacks that the client
6693  * implements.
6694  *
6695  * \param index_callbacks_size Size of #IndexerCallbacks structure that gets
6696  * passed in index_callbacks.
6697  *
6698  * \param index_options A bitmask of options that affects how indexing is
6699  * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags.
6700  *
6701  * \param[out] out_TU pointer to store a \c CXTranslationUnit that can be
6702  * reused after indexing is finished. Set to \c NULL if you do not require it.
6703  *
6704  * \returns 0 on success or if there were errors from which the compiler could
6705  * recover.  If there is a failure from which there is no recovery, returns
6706  * a non-zero \c CXErrorCode.
6707  *
6708  * The rest of the parameters are the same as #clang_parseTranslationUnit.
6709  */
6710 CINDEX_LINKAGE int clang_indexSourceFile(
6711     CXIndexAction, CXClientData client_data, IndexerCallbacks *index_callbacks,
6712     unsigned index_callbacks_size, unsigned index_options,
6713     const char *source_filename, const char *const *command_line_args,
6714     int num_command_line_args, struct CXUnsavedFile *unsaved_files,
6715     unsigned num_unsaved_files, CXTranslationUnit *out_TU, unsigned TU_options);
6716 
6717 /**
6718  * Same as clang_indexSourceFile but requires a full command line
6719  * for \c command_line_args including argv[0]. This is useful if the standard
6720  * library paths are relative to the binary.
6721  */
6722 CINDEX_LINKAGE int clang_indexSourceFileFullArgv(
6723     CXIndexAction, CXClientData client_data, IndexerCallbacks *index_callbacks,
6724     unsigned index_callbacks_size, unsigned index_options,
6725     const char *source_filename, const char *const *command_line_args,
6726     int num_command_line_args, struct CXUnsavedFile *unsaved_files,
6727     unsigned num_unsaved_files, CXTranslationUnit *out_TU, unsigned TU_options);
6728 
6729 /**
6730  * Index the given translation unit via callbacks implemented through
6731  * #IndexerCallbacks.
6732  *
6733  * The order of callback invocations is not guaranteed to be the same as
6734  * when indexing a source file. The high level order will be:
6735  *
6736  *   -Preprocessor callbacks invocations
6737  *   -Declaration/reference callbacks invocations
6738  *   -Diagnostic callback invocations
6739  *
6740  * The parameters are the same as #clang_indexSourceFile.
6741  *
6742  * \returns If there is a failure from which there is no recovery, returns
6743  * non-zero, otherwise returns 0.
6744  */
6745 CINDEX_LINKAGE int clang_indexTranslationUnit(
6746     CXIndexAction, CXClientData client_data, IndexerCallbacks *index_callbacks,
6747     unsigned index_callbacks_size, unsigned index_options, CXTranslationUnit);
6748 
6749 /**
6750  * Retrieve the CXIdxFile, file, line, column, and offset represented by
6751  * the given CXIdxLoc.
6752  *
6753  * If the location refers into a macro expansion, retrieves the
6754  * location of the macro expansion and if it refers into a macro argument
6755  * retrieves the location of the argument.
6756  */
6757 CINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc,
6758                                                    CXIdxClientFile *indexFile,
6759                                                    CXFile *file, unsigned *line,
6760                                                    unsigned *column,
6761                                                    unsigned *offset);
6762 
6763 /**
6764  * Retrieve the CXSourceLocation represented by the given CXIdxLoc.
6765  */
6766 CINDEX_LINKAGE
6767 CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc);
6768 
6769 /**
6770  * Visitor invoked for each field found by a traversal.
6771  *
6772  * This visitor function will be invoked for each field found by
6773  * \c clang_Type_visitFields. Its first argument is the cursor being
6774  * visited, its second argument is the client data provided to
6775  * \c clang_Type_visitFields.
6776  *
6777  * The visitor should return one of the \c CXVisitorResult values
6778  * to direct \c clang_Type_visitFields.
6779  */
6780 typedef enum CXVisitorResult (*CXFieldVisitor)(CXCursor C,
6781                                                CXClientData client_data);
6782 
6783 /**
6784  * Visit the fields of a particular type.
6785  *
6786  * This function visits all the direct fields of the given cursor,
6787  * invoking the given \p visitor function with the cursors of each
6788  * visited field. The traversal may be ended prematurely, if
6789  * the visitor returns \c CXFieldVisit_Break.
6790  *
6791  * \param T the record type whose field may be visited.
6792  *
6793  * \param visitor the visitor function that will be invoked for each
6794  * field of \p T.
6795  *
6796  * \param client_data pointer data supplied by the client, which will
6797  * be passed to the visitor each time it is invoked.
6798  *
6799  * \returns a non-zero value if the traversal was terminated
6800  * prematurely by the visitor returning \c CXFieldVisit_Break.
6801  */
6802 CINDEX_LINKAGE unsigned clang_Type_visitFields(CXType T, CXFieldVisitor visitor,
6803                                                CXClientData client_data);
6804 
6805 /**
6806  * @}
6807  */
6808 
6809 /**
6810  * @}
6811  */
6812 
6813 LLVM_CLANG_C_EXTERN_C_END
6814 
6815 #endif
6816