clang  7.0.0svn
Index.h
Go to the documentation of this file.
1 /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
2 |* *|
3 |* The LLVM Compiler Infrastructure *|
4 |* *|
5 |* This file is distributed under the University of Illinois Open Source *|
6 |* License. See LICENSE.TXT for details. *|
7 |* *|
8 |*===----------------------------------------------------------------------===*|
9 |* *|
10 |* This header provides a public 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/Platform.h"
22 #include "clang-c/CXErrorCode.h"
23 #include "clang-c/CXString.h"
24 #include "clang-c/BuildSystem.h"
25 
26 /**
27  * \brief The version constants for the libclang API.
28  * CINDEX_VERSION_MINOR should increase when there are API additions.
29  * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes.
30  *
31  * The policy about the libclang API was always to keep it source and ABI
32  * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable.
33  */
34 #define CINDEX_VERSION_MAJOR 0
35 #define CINDEX_VERSION_MINOR 48
36 
37 #define CINDEX_VERSION_ENCODE(major, minor) ( \
38  ((major) * 10000) \
39  + ((minor) * 1))
40 
41 #define CINDEX_VERSION CINDEX_VERSION_ENCODE( \
42  CINDEX_VERSION_MAJOR, \
43  CINDEX_VERSION_MINOR )
44 
45 #define CINDEX_VERSION_STRINGIZE_(major, minor) \
46  #major"."#minor
47 #define CINDEX_VERSION_STRINGIZE(major, minor) \
48  CINDEX_VERSION_STRINGIZE_(major, minor)
49 
50 #define CINDEX_VERSION_STRING CINDEX_VERSION_STRINGIZE( \
51  CINDEX_VERSION_MAJOR, \
52  CINDEX_VERSION_MINOR)
53 
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57 
58 /** \defgroup CINDEX libclang: C Interface to Clang
59  *
60  * The C Interface to Clang provides a relatively small API that exposes
61  * facilities for parsing source code into an abstract syntax tree (AST),
62  * loading already-parsed ASTs, traversing the AST, associating
63  * physical source locations with elements within the AST, and other
64  * facilities that support Clang-based development tools.
65  *
66  * This C interface to Clang will never provide all of the information
67  * representation stored in Clang's C++ AST, nor should it: the intent is to
68  * maintain an API that is relatively stable from one release to the next,
69  * providing only the basic functionality needed to support development tools.
70  *
71  * To avoid namespace pollution, data types are prefixed with "CX" and
72  * functions are prefixed with "clang_".
73  *
74  * @{
75  */
76 
77 /**
78  * \brief An "index" that consists of a set of translation units that would
79  * typically be linked together into an executable or library.
80  */
81 typedef void *CXIndex;
82 
83 /**
84  * \brief An opaque type representing target information for a given translation
85  * unit.
86  */
87 typedef struct CXTargetInfoImpl *CXTargetInfo;
88 
89 /**
90  * \brief A single translation unit, which resides in an index.
91  */
92 typedef struct CXTranslationUnitImpl *CXTranslationUnit;
93 
94 /**
95  * \brief Opaque pointer representing client data that will be passed through
96  * to various callbacks and visitors.
97  */
98 typedef void *CXClientData;
99 
100 /**
101  * \brief Provides the contents of a file that has not yet been saved to disk.
102  *
103  * Each CXUnsavedFile instance provides the name of a file on the
104  * system along with the current contents of that file that have not
105  * yet been saved to disk.
106  */
108  /**
109  * \brief The file whose contents have not yet been saved.
110  *
111  * This file must already exist in the file system.
112  */
113  const char *Filename;
114 
115  /**
116  * \brief A buffer containing the unsaved contents of this file.
117  */
118  const char *Contents;
119 
120  /**
121  * \brief The length of the unsaved contents of this buffer.
122  */
123  unsigned long Length;
124 };
125 
126 /**
127  * \brief Describes the availability of a particular entity, which indicates
128  * whether the use of this entity will result in a warning or error due to
129  * it being deprecated or unavailable.
130  */
132  /**
133  * \brief The entity is available.
134  */
136  /**
137  * \brief The entity is available, but has been deprecated (and its use is
138  * not recommended).
139  */
141  /**
142  * \brief The entity is not available; any use of it will be an error.
143  */
145  /**
146  * \brief The entity is available, but not accessible; any use of it will be
147  * an error.
148  */
150 };
151 
152 /**
153  * \brief Describes a version number of the form major.minor.subminor.
154  */
155 typedef struct CXVersion {
156  /**
157  * \brief The major version number, e.g., the '10' in '10.7.3'. A negative
158  * value indicates that there is no version number at all.
159  */
160  int Major;
161  /**
162  * \brief The minor version number, e.g., the '7' in '10.7.3'. This value
163  * will be negative if no minor version number was provided, e.g., for
164  * version '10'.
165  */
166  int Minor;
167  /**
168  * \brief The subminor version number, e.g., the '3' in '10.7.3'. This value
169  * will be negative if no minor or subminor version number was provided,
170  * e.g., in version '10' or '10.7'.
171  */
172  int Subminor;
173 } CXVersion;
174 
175 /**
176  * \brief Describes the exception specification of a cursor.
177  *
178  * A negative value indicates that the cursor is not a function declaration.
179  */
181 
182  /**
183  * \brief The cursor has no exception specification.
184  */
186 
187  /**
188  * \brief The cursor has exception specification throw()
189  */
191 
192  /**
193  * \brief The cursor has exception specification throw(T1, T2)
194  */
196 
197  /**
198  * \brief The cursor has exception specification throw(...).
199  */
201 
202  /**
203  * \brief The cursor has exception specification basic noexcept.
204  */
206 
207  /**
208  * \brief The cursor has exception specification computed noexcept.
209  */
211 
212  /**
213  * \brief The exception specification has not yet been evaluated.
214  */
216 
217  /**
218  * \brief The exception specification has not yet been instantiated.
219  */
221 
222  /**
223  * \brief The exception specification has not been parsed yet.
224  */
226 };
227 
228 /**
229  * \brief Provides a shared context for creating translation units.
230  *
231  * It provides two options:
232  *
233  * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
234  * declarations (when loading any new translation units). A "local" declaration
235  * is one that belongs in the translation unit itself and not in a precompiled
236  * header that was used by the translation unit. If zero, all declarations
237  * will be enumerated.
238  *
239  * Here is an example:
240  *
241  * \code
242  * // excludeDeclsFromPCH = 1, displayDiagnostics=1
243  * Idx = clang_createIndex(1, 1);
244  *
245  * // IndexTest.pch was produced with the following command:
246  * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
247  * TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
248  *
249  * // This will load all the symbols from 'IndexTest.pch'
250  * clang_visitChildren(clang_getTranslationUnitCursor(TU),
251  * TranslationUnitVisitor, 0);
252  * clang_disposeTranslationUnit(TU);
253  *
254  * // This will load all the symbols from 'IndexTest.c', excluding symbols
255  * // from 'IndexTest.pch'.
256  * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
257  * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
258  * 0, 0);
259  * clang_visitChildren(clang_getTranslationUnitCursor(TU),
260  * TranslationUnitVisitor, 0);
261  * clang_disposeTranslationUnit(TU);
262  * \endcode
263  *
264  * This process of creating the 'pch', loading it separately, and using it (via
265  * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
266  * (which gives the indexer the same performance benefit as the compiler).
267  */
268 CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
269  int displayDiagnostics);
270 
271 /**
272  * \brief Destroy the given index.
273  *
274  * The index must not be destroyed until all of the translation units created
275  * within that index have been destroyed.
276  */
277 CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
278 
279 typedef enum {
280  /**
281  * \brief Used to indicate that no special CXIndex options are needed.
282  */
284 
285  /**
286  * \brief Used to indicate that threads that libclang creates for indexing
287  * purposes should use background priority.
288  *
289  * Affects #clang_indexSourceFile, #clang_indexTranslationUnit,
290  * #clang_parseTranslationUnit, #clang_saveTranslationUnit.
291  */
293 
294  /**
295  * \brief Used to indicate that threads that libclang creates for editing
296  * purposes should use background priority.
297  *
298  * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt,
299  * #clang_annotateTokens
300  */
302 
303  /**
304  * \brief Used to indicate that all threads that libclang creates should use
305  * background priority.
306  */
310 
312 
313 /**
314  * \brief Sets general options associated with a CXIndex.
315  *
316  * For example:
317  * \code
318  * CXIndex idx = ...;
319  * clang_CXIndex_setGlobalOptions(idx,
320  * clang_CXIndex_getGlobalOptions(idx) |
321  * CXGlobalOpt_ThreadBackgroundPriorityForIndexing);
322  * \endcode
323  *
324  * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags.
325  */
326 CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options);
327 
328 /**
329  * \brief Gets the general options associated with a CXIndex.
330  *
331  * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that
332  * are associated with the given CXIndex object.
333  */
335 
336 /**
337  * \brief Sets the invocation emission path option in a CXIndex.
338  *
339  * The invocation emission path specifies a path which will contain log
340  * files for certain libclang invocations. A null value (default) implies that
341  * libclang invocations are not logged..
342  */
343 CINDEX_LINKAGE void
344 clang_CXIndex_setInvocationEmissionPathOption(CXIndex, const char *Path);
345 
346 /**
347  * \defgroup CINDEX_FILES File manipulation routines
348  *
349  * @{
350  */
351 
352 /**
353  * \brief A particular source file that is part of a translation unit.
354  */
355 typedef void *CXFile;
356 
357 /**
358  * \brief Retrieve the complete file and path name of the given file.
359  */
361 
362 /**
363  * \brief Retrieve the last modification time of the given file.
364  */
365 CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
366 
367 /**
368  * \brief Uniquely identifies a CXFile, that refers to the same underlying file,
369  * across an indexing session.
370  */
371 typedef struct {
372  unsigned long long data[3];
374 
375 /**
376  * \brief Retrieve the unique ID for the given \c file.
377  *
378  * \param file the file to get the ID for.
379  * \param outID stores the returned CXFileUniqueID.
380  * \returns If there was a failure getting the unique ID, returns non-zero,
381  * otherwise returns 0.
382 */
383 CINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID);
384 
385 /**
386  * \brief Determine whether the given header is guarded against
387  * multiple inclusions, either with the conventional
388  * \#ifndef/\#define/\#endif macro guards or with \#pragma once.
389  */
390 CINDEX_LINKAGE unsigned
391 clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file);
392 
393 /**
394  * \brief Retrieve a file handle within the given translation unit.
395  *
396  * \param tu the translation unit
397  *
398  * \param file_name the name of the file.
399  *
400  * \returns the file handle for the named file in the translation unit \p tu,
401  * or a NULL file handle if the file was not a part of this translation unit.
402  */
403 CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
404  const char *file_name);
405 
406 /**
407  * \brief Retrieve the buffer associated with the given file.
408  *
409  * \param tu the translation unit
410  *
411  * \param file the file for which to retrieve the buffer.
412  *
413  * \param size [out] if non-NULL, will be set to the size of the buffer.
414  *
415  * \returns a pointer to the buffer in memory that holds the contents of
416  * \p file, or a NULL pointer when the file is not loaded.
417  */
418 CINDEX_LINKAGE const char *clang_getFileContents(CXTranslationUnit tu,
419  CXFile file, size_t *size);
420 
421 /**
422  * \brief Returns non-zero if the \c file1 and \c file2 point to the same file,
423  * or they are both NULL.
424  */
425 CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2);
426 
427 /**
428  * \brief Returns the real path name of \c file.
429  *
430  * An empty string may be returned. Use \c clang_getFileName() in that case.
431  */
433 
434 /**
435  * @}
436  */
437 
438 /**
439  * \defgroup CINDEX_LOCATIONS Physical source locations
440  *
441  * Clang represents physical source locations in its abstract syntax tree in
442  * great detail, with file, line, and column information for the majority of
443  * the tokens parsed in the source code. These data types and functions are
444  * used to represent source location information, either for a particular
445  * point in the program or for a range of points in the program, and extract
446  * specific location information from those data types.
447  *
448  * @{
449  */
450 
451 /**
452  * \brief Identifies a specific source location within a translation
453  * unit.
454  *
455  * Use clang_getExpansionLocation() or clang_getSpellingLocation()
456  * to map a source location to a particular file, line, and column.
457  */
458 typedef struct {
459  const void *ptr_data[2];
460  unsigned int_data;
462 
463 /**
464  * \brief Identifies a half-open character range in the source code.
465  *
466  * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
467  * starting and end locations from a source range, respectively.
468  */
469 typedef struct {
470  const void *ptr_data[2];
471  unsigned begin_int_data;
472  unsigned end_int_data;
473 } CXSourceRange;
474 
475 /**
476  * \brief Retrieve a NULL (invalid) source location.
477  */
479 
480 /**
481  * \brief Determine whether two source locations, which must refer into
482  * the same translation unit, refer to exactly the same point in the source
483  * code.
484  *
485  * \returns non-zero if the source locations refer to the same location, zero
486  * if they refer to different locations.
487  */
489  CXSourceLocation loc2);
490 
491 /**
492  * \brief Retrieves the source location associated with a given file/line/column
493  * in a particular translation unit.
494  */
496  CXFile file,
497  unsigned line,
498  unsigned column);
499 /**
500  * \brief Retrieves the source location associated with a given character offset
501  * in a particular translation unit.
502  */
504  CXFile file,
505  unsigned offset);
506 
507 /**
508  * \brief Returns non-zero if the given source location is in a system header.
509  */
511 
512 /**
513  * \brief Returns non-zero if the given source location is in the main file of
514  * the corresponding translation unit.
515  */
517 
518 /**
519  * \brief Retrieve a NULL (invalid) source range.
520  */
522 
523 /**
524  * \brief Retrieve a source range given the beginning and ending source
525  * locations.
526  */
528  CXSourceLocation end);
529 
530 /**
531  * \brief Determine whether two ranges are equivalent.
532  *
533  * \returns non-zero if the ranges are the same, zero if they differ.
534  */
536  CXSourceRange range2);
537 
538 /**
539  * \brief Returns non-zero if \p range is null.
540  */
542 
543 /**
544  * \brief Retrieve the file, line, column, and offset represented by
545  * the given source location.
546  *
547  * If the location refers into a macro expansion, retrieves the
548  * location of the macro expansion.
549  *
550  * \param location the location within a source file that will be decomposed
551  * into its parts.
552  *
553  * \param file [out] if non-NULL, will be set to the file to which the given
554  * source location points.
555  *
556  * \param line [out] if non-NULL, will be set to the line to which the given
557  * source location points.
558  *
559  * \param column [out] if non-NULL, will be set to the column to which the given
560  * source location points.
561  *
562  * \param offset [out] if non-NULL, will be set to the offset into the
563  * buffer to which the given source location points.
564  */
566  CXFile *file,
567  unsigned *line,
568  unsigned *column,
569  unsigned *offset);
570 
571 /**
572  * \brief Retrieve the file, line and column represented by the given source
573  * location, as specified in a # line directive.
574  *
575  * Example: given the following source code in a file somefile.c
576  *
577  * \code
578  * #123 "dummy.c" 1
579  *
580  * static int func(void)
581  * {
582  * return 0;
583  * }
584  * \endcode
585  *
586  * the location information returned by this function would be
587  *
588  * File: dummy.c Line: 124 Column: 12
589  *
590  * whereas clang_getExpansionLocation would have returned
591  *
592  * File: somefile.c Line: 3 Column: 12
593  *
594  * \param location the location within a source file that will be decomposed
595  * into its parts.
596  *
597  * \param filename [out] if non-NULL, will be set to the filename of the
598  * source location. Note that filenames returned will be for "virtual" files,
599  * which don't necessarily exist on the machine running clang - e.g. when
600  * parsing preprocessed output obtained from a different environment. If
601  * a non-NULL value is passed in, remember to dispose of the returned value
602  * using \c clang_disposeString() once you've finished with it. For an invalid
603  * source location, an empty string is returned.
604  *
605  * \param line [out] if non-NULL, will be set to the line number of the
606  * source location. For an invalid source location, zero is returned.
607  *
608  * \param column [out] if non-NULL, will be set to the column number of the
609  * source location. For an invalid source location, zero is returned.
610  */
612  CXString *filename,
613  unsigned *line,
614  unsigned *column);
615 
616 /**
617  * \brief Legacy API to retrieve the file, line, column, and offset represented
618  * by the given source location.
619  *
620  * This interface has been replaced by the newer interface
621  * #clang_getExpansionLocation(). See that interface's documentation for
622  * details.
623  */
625  CXFile *file,
626  unsigned *line,
627  unsigned *column,
628  unsigned *offset);
629 
630 /**
631  * \brief Retrieve the file, line, column, and offset represented by
632  * the given source location.
633  *
634  * If the location refers into a macro instantiation, return where the
635  * location was originally spelled in the source file.
636  *
637  * \param location the location within a source file that will be decomposed
638  * into its parts.
639  *
640  * \param file [out] if non-NULL, will be set to the file to which the given
641  * source location points.
642  *
643  * \param line [out] if non-NULL, will be set to the line to which the given
644  * source location points.
645  *
646  * \param column [out] if non-NULL, will be set to the column to which the given
647  * source location points.
648  *
649  * \param offset [out] if non-NULL, will be set to the offset into the
650  * buffer to which the given source location points.
651  */
653  CXFile *file,
654  unsigned *line,
655  unsigned *column,
656  unsigned *offset);
657 
658 /**
659  * \brief Retrieve the file, line, column, and offset represented by
660  * the given source location.
661  *
662  * If the location refers into a macro expansion, return where the macro was
663  * expanded or where the macro argument was written, if the location points at
664  * a macro argument.
665  *
666  * \param location the location within a source file that will be decomposed
667  * into its parts.
668  *
669  * \param file [out] if non-NULL, will be set to the file to which the given
670  * source location points.
671  *
672  * \param line [out] if non-NULL, will be set to the line to which the given
673  * source location points.
674  *
675  * \param column [out] if non-NULL, will be set to the column to which the given
676  * source location points.
677  *
678  * \param offset [out] if non-NULL, will be set to the offset into the
679  * buffer to which the given source location points.
680  */
682  CXFile *file,
683  unsigned *line,
684  unsigned *column,
685  unsigned *offset);
686 
687 /**
688  * \brief Retrieve a source location representing the first character within a
689  * source range.
690  */
692 
693 /**
694  * \brief Retrieve a source location representing the last character within a
695  * source range.
696  */
698 
699 /**
700  * \brief Identifies an array of ranges.
701  */
702 typedef struct {
703  /** \brief The number of ranges in the \c ranges array. */
704  unsigned count;
705  /**
706  * \brief An array of \c CXSourceRanges.
707  */
710 
711 /**
712  * \brief Retrieve all ranges that were skipped by the preprocessor.
713  *
714  * The preprocessor will skip lines when they are surrounded by an
715  * if/ifdef/ifndef directive whose condition does not evaluate to true.
716  */
718  CXFile file);
719 
720 /**
721  * \brief Retrieve all ranges from all files that were skipped by the
722  * preprocessor.
723  *
724  * The preprocessor will skip lines when they are surrounded by an
725  * if/ifdef/ifndef directive whose condition does not evaluate to true.
726  */
728 
729 /**
730  * \brief Destroy the given \c CXSourceRangeList.
731  */
733 
734 /**
735  * @}
736  */
737 
738 /**
739  * \defgroup CINDEX_DIAG Diagnostic reporting
740  *
741  * @{
742  */
743 
744 /**
745  * \brief Describes the severity of a particular diagnostic.
746  */
748  /**
749  * \brief A diagnostic that has been suppressed, e.g., by a command-line
750  * option.
751  */
753 
754  /**
755  * \brief This diagnostic is a note that should be attached to the
756  * previous (non-note) diagnostic.
757  */
759 
760  /**
761  * \brief This diagnostic indicates suspicious code that may not be
762  * wrong.
763  */
765 
766  /**
767  * \brief This diagnostic indicates that the code is ill-formed.
768  */
770 
771  /**
772  * \brief This diagnostic indicates that the code is ill-formed such
773  * that future parser recovery is unlikely to produce useful
774  * results.
775  */
777 };
778 
779 /**
780  * \brief A single diagnostic, containing the diagnostic's severity,
781  * location, text, source ranges, and fix-it hints.
782  */
783 typedef void *CXDiagnostic;
784 
785 /**
786  * \brief A group of CXDiagnostics.
787  */
788 typedef void *CXDiagnosticSet;
789 
790 /**
791  * \brief Determine the number of diagnostics in a CXDiagnosticSet.
792  */
793 CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);
794 
795 /**
796  * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet.
797  *
798  * \param Diags the CXDiagnosticSet to query.
799  * \param Index the zero-based diagnostic number to retrieve.
800  *
801  * \returns the requested diagnostic. This diagnostic must be freed
802  * via a call to \c clang_disposeDiagnostic().
803  */
804 CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,
805  unsigned Index);
806 
807 /**
808  * \brief Describes the kind of error that occurred (if any) in a call to
809  * \c clang_loadDiagnostics.
810  */
812  /**
813  * \brief Indicates that no error occurred.
814  */
816 
817  /**
818  * \brief Indicates that an unknown error occurred while attempting to
819  * deserialize diagnostics.
820  */
822 
823  /**
824  * \brief Indicates that the file containing the serialized diagnostics
825  * could not be opened.
826  */
828 
829  /**
830  * \brief Indicates that the serialized diagnostics file is invalid or
831  * corrupt.
832  */
834 };
835 
836 /**
837  * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode
838  * file.
839  *
840  * \param file The name of the file to deserialize.
841  * \param error A pointer to a enum value recording if there was a problem
842  * deserializing the diagnostics.
843  * \param errorString A pointer to a CXString for recording the error string
844  * if the file was not successfully loaded.
845  *
846  * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These
847  * diagnostics should be released using clang_disposeDiagnosticSet().
848  */
849 CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file,
850  enum CXLoadDiag_Error *error,
851  CXString *errorString);
852 
853 /**
854  * \brief Release a CXDiagnosticSet and all of its contained diagnostics.
855  */
856 CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);
857 
858 /**
859  * \brief Retrieve the child diagnostics of a CXDiagnostic.
860  *
861  * This CXDiagnosticSet does not need to be released by
862  * clang_disposeDiagnosticSet.
863  */
864 CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);
865 
866 /**
867  * \brief Determine the number of diagnostics produced for the given
868  * translation unit.
869  */
870 CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit);
871 
872 /**
873  * \brief Retrieve a diagnostic associated with the given translation unit.
874  *
875  * \param Unit the translation unit to query.
876  * \param Index the zero-based diagnostic number to retrieve.
877  *
878  * \returns the requested diagnostic. This diagnostic must be freed
879  * via a call to \c clang_disposeDiagnostic().
880  */
881 CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit,
882  unsigned Index);
883 
884 /**
885  * \brief Retrieve the complete set of diagnostics associated with a
886  * translation unit.
887  *
888  * \param Unit the translation unit to query.
889  */
890 CINDEX_LINKAGE CXDiagnosticSet
891  clang_getDiagnosticSetFromTU(CXTranslationUnit Unit);
892 
893 /**
894  * \brief Destroy a diagnostic.
895  */
896 CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
897 
898 /**
899  * \brief Options to control the display of diagnostics.
900  *
901  * The values in this enum are meant to be combined to customize the
902  * behavior of \c clang_formatDiagnostic().
903  */
905  /**
906  * \brief Display the source-location information where the
907  * diagnostic was located.
908  *
909  * When set, diagnostics will be prefixed by the file, line, and
910  * (optionally) column to which the diagnostic refers. For example,
911  *
912  * \code
913  * test.c:28: warning: extra tokens at end of #endif directive
914  * \endcode
915  *
916  * This option corresponds to the clang flag \c -fshow-source-location.
917  */
919 
920  /**
921  * \brief If displaying the source-location information of the
922  * diagnostic, also include the column number.
923  *
924  * This option corresponds to the clang flag \c -fshow-column.
925  */
927 
928  /**
929  * \brief If displaying the source-location information of the
930  * diagnostic, also include information about source ranges in a
931  * machine-parsable format.
932  *
933  * This option corresponds to the clang flag
934  * \c -fdiagnostics-print-source-range-info.
935  */
937 
938  /**
939  * \brief Display the option name associated with this diagnostic, if any.
940  *
941  * The option name displayed (e.g., -Wconversion) will be placed in brackets
942  * after the diagnostic text. This option corresponds to the clang flag
943  * \c -fdiagnostics-show-option.
944  */
946 
947  /**
948  * \brief Display the category number associated with this diagnostic, if any.
949  *
950  * The category number is displayed within brackets after the diagnostic text.
951  * This option corresponds to the clang flag
952  * \c -fdiagnostics-show-category=id.
953  */
955 
956  /**
957  * \brief Display the category name associated with this diagnostic, if any.
958  *
959  * The category name is displayed within brackets after the diagnostic text.
960  * This option corresponds to the clang flag
961  * \c -fdiagnostics-show-category=name.
962  */
964 };
965 
966 /**
967  * \brief Format the given diagnostic in a manner that is suitable for display.
968  *
969  * This routine will format the given diagnostic to a string, rendering
970  * the diagnostic according to the various options given. The
971  * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
972  * options that most closely mimics the behavior of the clang compiler.
973  *
974  * \param Diagnostic The diagnostic to print.
975  *
976  * \param Options A set of options that control the diagnostic display,
977  * created by combining \c CXDiagnosticDisplayOptions values.
978  *
979  * \returns A new string containing for formatted diagnostic.
980  */
981 CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
982  unsigned Options);
983 
984 /**
985  * \brief Retrieve the set of display options most similar to the
986  * default behavior of the clang compiler.
987  *
988  * \returns A set of display options suitable for use with \c
989  * clang_formatDiagnostic().
990  */
992 
993 /**
994  * \brief Determine the severity of the given diagnostic.
995  */
997 clang_getDiagnosticSeverity(CXDiagnostic);
998 
999 /**
1000  * \brief Retrieve the source location of the given diagnostic.
1001  *
1002  * This location is where Clang would print the caret ('^') when
1003  * displaying the diagnostic on the command line.
1004  */
1006 
1007 /**
1008  * \brief Retrieve the text of the given diagnostic.
1009  */
1011 
1012 /**
1013  * \brief Retrieve the name of the command-line option that enabled this
1014  * diagnostic.
1015  *
1016  * \param Diag The diagnostic to be queried.
1017  *
1018  * \param Disable If non-NULL, will be set to the option that disables this
1019  * diagnostic (if any).
1020  *
1021  * \returns A string that contains the command-line option used to enable this
1022  * warning, such as "-Wconversion" or "-pedantic".
1023  */
1025  CXString *Disable);
1026 
1027 /**
1028  * \brief Retrieve the category number for this diagnostic.
1029  *
1030  * Diagnostics can be categorized into groups along with other, related
1031  * diagnostics (e.g., diagnostics under the same warning flag). This routine
1032  * retrieves the category number for the given diagnostic.
1033  *
1034  * \returns The number of the category that contains this diagnostic, or zero
1035  * if this diagnostic is uncategorized.
1036  */
1037 CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);
1038 
1039 /**
1040  * \brief Retrieve the name of a particular diagnostic category. This
1041  * is now deprecated. Use clang_getDiagnosticCategoryText()
1042  * instead.
1043  *
1044  * \param Category A diagnostic category number, as returned by
1045  * \c clang_getDiagnosticCategory().
1046  *
1047  * \returns The name of the given diagnostic category.
1048  */
1051 
1052 /**
1053  * \brief Retrieve the diagnostic category text for a given diagnostic.
1054  *
1055  * \returns The text of the given diagnostic category.
1056  */
1058 
1059 /**
1060  * \brief Determine the number of source ranges associated with the given
1061  * diagnostic.
1062  */
1063 CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
1064 
1065 /**
1066  * \brief Retrieve a source range associated with the diagnostic.
1067  *
1068  * A diagnostic's source ranges highlight important elements in the source
1069  * code. On the command line, Clang displays source ranges by
1070  * underlining them with '~' characters.
1071  *
1072  * \param Diagnostic the diagnostic whose range is being extracted.
1073  *
1074  * \param Range the zero-based index specifying which range to
1075  *
1076  * \returns the requested source range.
1077  */
1078 CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
1079  unsigned Range);
1080 
1081 /**
1082  * \brief Determine the number of fix-it hints associated with the
1083  * given diagnostic.
1084  */
1085 CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
1086 
1087 /**
1088  * \brief Retrieve the replacement information for a given fix-it.
1089  *
1090  * Fix-its are described in terms of a source range whose contents
1091  * should be replaced by a string. This approach generalizes over
1092  * three kinds of operations: removal of source code (the range covers
1093  * the code to be removed and the replacement string is empty),
1094  * replacement of source code (the range covers the code to be
1095  * replaced and the replacement string provides the new code), and
1096  * insertion (both the start and end of the range point at the
1097  * insertion location, and the replacement string provides the text to
1098  * insert).
1099  *
1100  * \param Diagnostic The diagnostic whose fix-its are being queried.
1101  *
1102  * \param FixIt The zero-based index of the fix-it.
1103  *
1104  * \param ReplacementRange The source range whose contents will be
1105  * replaced with the returned replacement string. Note that source
1106  * ranges are half-open ranges [a, b), so the source code should be
1107  * replaced from a and up to (but not including) b.
1108  *
1109  * \returns A string containing text that should be replace the source
1110  * code indicated by the \c ReplacementRange.
1111  */
1112 CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic,
1113  unsigned FixIt,
1114  CXSourceRange *ReplacementRange);
1115 
1116 /**
1117  * @}
1118  */
1119 
1120 /**
1121  * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
1122  *
1123  * The routines in this group provide the ability to create and destroy
1124  * translation units from files, either by parsing the contents of the files or
1125  * by reading in a serialized representation of a translation unit.
1126  *
1127  * @{
1128  */
1129 
1130 /**
1131  * \brief Get the original translation unit source file name.
1132  */
1134 clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
1135 
1136 /**
1137  * \brief Return the CXTranslationUnit for a given source file and the provided
1138  * command line arguments one would pass to the compiler.
1139  *
1140  * Note: The 'source_filename' argument is optional. If the caller provides a
1141  * NULL pointer, the name of the source file is expected to reside in the
1142  * specified command line arguments.
1143  *
1144  * Note: When encountered in 'clang_command_line_args', the following options
1145  * are ignored:
1146  *
1147  * '-c'
1148  * '-emit-ast'
1149  * '-fsyntax-only'
1150  * '-o <output file>' (both '-o' and '<output file>' are ignored)
1151  *
1152  * \param CIdx The index object with which the translation unit will be
1153  * associated.
1154  *
1155  * \param source_filename The name of the source file to load, or NULL if the
1156  * source file is included in \p clang_command_line_args.
1157  *
1158  * \param num_clang_command_line_args The number of command-line arguments in
1159  * \p clang_command_line_args.
1160  *
1161  * \param clang_command_line_args The command-line arguments that would be
1162  * passed to the \c clang executable if it were being invoked out-of-process.
1163  * These command-line options will be parsed and will affect how the translation
1164  * unit is parsed. Note that the following options are ignored: '-c',
1165  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.
1166  *
1167  * \param num_unsaved_files the number of unsaved file entries in \p
1168  * unsaved_files.
1169  *
1170  * \param unsaved_files the files that have not yet been saved to disk
1171  * but may be required for code completion, including the contents of
1172  * those files. The contents and name of these files (as specified by
1173  * CXUnsavedFile) are copied when necessary, so the client only needs to
1174  * guarantee their validity until the call to this function returns.
1175  */
1177  CXIndex CIdx,
1178  const char *source_filename,
1179  int num_clang_command_line_args,
1180  const char * const *clang_command_line_args,
1181  unsigned num_unsaved_files,
1182  struct CXUnsavedFile *unsaved_files);
1183 
1184 /**
1185  * \brief Same as \c clang_createTranslationUnit2, but returns
1186  * the \c CXTranslationUnit instead of an error code. In case of an error this
1187  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
1188  * error codes.
1189  */
1191  CXIndex CIdx,
1192  const char *ast_filename);
1193 
1194 /**
1195  * \brief Create a translation unit from an AST file (\c -emit-ast).
1196  *
1197  * \param[out] out_TU A non-NULL pointer to store the created
1198  * \c CXTranslationUnit.
1199  *
1200  * \returns Zero on success, otherwise returns an error code.
1201  */
1203  CXIndex CIdx,
1204  const char *ast_filename,
1205  CXTranslationUnit *out_TU);
1206 
1207 /**
1208  * \brief Flags that control the creation of translation units.
1209  *
1210  * The enumerators in this enumeration type are meant to be bitwise
1211  * ORed together to specify which options should be used when
1212  * constructing the translation unit.
1213  */
1215  /**
1216  * \brief Used to indicate that no special translation-unit options are
1217  * needed.
1218  */
1220 
1221  /**
1222  * \brief Used to indicate that the parser should construct a "detailed"
1223  * preprocessing record, including all macro definitions and instantiations.
1224  *
1225  * Constructing a detailed preprocessing record requires more memory
1226  * and time to parse, since the information contained in the record
1227  * is usually not retained. However, it can be useful for
1228  * applications that require more detailed information about the
1229  * behavior of the preprocessor.
1230  */
1232 
1233  /**
1234  * \brief Used to indicate that the translation unit is incomplete.
1235  *
1236  * When a translation unit is considered "incomplete", semantic
1237  * analysis that is typically performed at the end of the
1238  * translation unit will be suppressed. For example, this suppresses
1239  * the completion of tentative declarations in C and of
1240  * instantiation of implicitly-instantiation function templates in
1241  * C++. This option is typically used when parsing a header with the
1242  * intent of producing a precompiled header.
1243  */
1245 
1246  /**
1247  * \brief Used to indicate that the translation unit should be built with an
1248  * implicit precompiled header for the preamble.
1249  *
1250  * An implicit precompiled header is used as an optimization when a
1251  * particular translation unit is likely to be reparsed many times
1252  * when the sources aren't changing that often. In this case, an
1253  * implicit precompiled header will be built containing all of the
1254  * initial includes at the top of the main file (what we refer to as
1255  * the "preamble" of the file). In subsequent parses, if the
1256  * preamble or the files in it have not changed, \c
1257  * clang_reparseTranslationUnit() will re-use the implicit
1258  * precompiled header to improve parsing performance.
1259  */
1261 
1262  /**
1263  * \brief Used to indicate that the translation unit should cache some
1264  * code-completion results with each reparse of the source file.
1265  *
1266  * Caching of code-completion results is a performance optimization that
1267  * introduces some overhead to reparsing but improves the performance of
1268  * code-completion operations.
1269  */
1271 
1272  /**
1273  * \brief Used to indicate that the translation unit will be serialized with
1274  * \c clang_saveTranslationUnit.
1275  *
1276  * This option is typically used when parsing a header with the intent of
1277  * producing a precompiled header.
1278  */
1280 
1281  /**
1282  * \brief DEPRECATED: Enabled chained precompiled preambles in C++.
1283  *
1284  * Note: this is a *temporary* option that is available only while
1285  * we are testing C++ precompiled preamble support. It is deprecated.
1286  */
1288 
1289  /**
1290  * \brief Used to indicate that function/method bodies should be skipped while
1291  * parsing.
1292  *
1293  * This option can be used to search for declarations/definitions while
1294  * ignoring the usages.
1295  */
1297 
1298  /**
1299  * \brief Used to indicate that brief documentation comments should be
1300  * included into the set of code completions returned from this translation
1301  * unit.
1302  */
1304 
1305  /**
1306  * \brief Used to indicate that the precompiled preamble should be created on
1307  * the first parse. Otherwise it will be created on the first reparse. This
1308  * trades runtime on the first parse (serializing the preamble takes time) for
1309  * reduced runtime on the second parse (can now reuse the preamble).
1310  */
1312 
1313  /**
1314  * \brief Do not stop processing when fatal errors are encountered.
1315  *
1316  * When fatal errors are encountered while parsing a translation unit,
1317  * semantic analysis is typically stopped early when compiling code. A common
1318  * source for fatal errors are unresolvable include files. For the
1319  * purposes of an IDE, this is undesirable behavior and as much information
1320  * as possible should be reported. Use this flag to enable this behavior.
1321  */
1323 
1324  /**
1325  * \brief Sets the preprocessor in a mode for parsing a single file only.
1326  */
1328 };
1329 
1330 /**
1331  * \brief Returns the set of flags that is suitable for parsing a translation
1332  * unit that is being edited.
1333  *
1334  * The set of flags returned provide options for \c clang_parseTranslationUnit()
1335  * to indicate that the translation unit is likely to be reparsed many times,
1336  * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
1337  * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
1338  * set contains an unspecified set of optimizations (e.g., the precompiled
1339  * preamble) geared toward improving the performance of these routines. The
1340  * set of optimizations enabled may change from one version to the next.
1341  */
1343 
1344 /**
1345  * \brief Same as \c clang_parseTranslationUnit2, but returns
1346  * the \c CXTranslationUnit instead of an error code. In case of an error this
1347  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
1348  * error codes.
1349  */
1350 CINDEX_LINKAGE CXTranslationUnit
1351 clang_parseTranslationUnit(CXIndex CIdx,
1352  const char *source_filename,
1353  const char *const *command_line_args,
1354  int num_command_line_args,
1355  struct CXUnsavedFile *unsaved_files,
1356  unsigned num_unsaved_files,
1357  unsigned options);
1358 
1359 /**
1360  * \brief Parse the given source file and the translation unit corresponding
1361  * to that file.
1362  *
1363  * This routine is the main entry point for the Clang C API, providing the
1364  * ability to parse a source file into a translation unit that can then be
1365  * queried by other functions in the API. This routine accepts a set of
1366  * command-line arguments so that the compilation can be configured in the same
1367  * way that the compiler is configured on the command line.
1368  *
1369  * \param CIdx The index object with which the translation unit will be
1370  * associated.
1371  *
1372  * \param source_filename The name of the source file to load, or NULL if the
1373  * source file is included in \c command_line_args.
1374  *
1375  * \param command_line_args The command-line arguments that would be
1376  * passed to the \c clang executable if it were being invoked out-of-process.
1377  * These command-line options will be parsed and will affect how the translation
1378  * unit is parsed. Note that the following options are ignored: '-c',
1379  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.
1380  *
1381  * \param num_command_line_args The number of command-line arguments in
1382  * \c command_line_args.
1383  *
1384  * \param unsaved_files the files that have not yet been saved to disk
1385  * but may be required for parsing, including the contents of
1386  * those files. The contents and name of these files (as specified by
1387  * CXUnsavedFile) are copied when necessary, so the client only needs to
1388  * guarantee their validity until the call to this function returns.
1389  *
1390  * \param num_unsaved_files the number of unsaved file entries in \p
1391  * unsaved_files.
1392  *
1393  * \param options A bitmask of options that affects how the translation unit
1394  * is managed but not its compilation. This should be a bitwise OR of the
1395  * CXTranslationUnit_XXX flags.
1396  *
1397  * \param[out] out_TU A non-NULL pointer to store the created
1398  * \c CXTranslationUnit, describing the parsed code and containing any
1399  * diagnostics produced by the compiler.
1400  *
1401  * \returns Zero on success, otherwise returns an error code.
1402  */
1404 clang_parseTranslationUnit2(CXIndex CIdx,
1405  const char *source_filename,
1406  const char *const *command_line_args,
1407  int num_command_line_args,
1408  struct CXUnsavedFile *unsaved_files,
1409  unsigned num_unsaved_files,
1410  unsigned options,
1411  CXTranslationUnit *out_TU);
1412 
1413 /**
1414  * \brief Same as clang_parseTranslationUnit2 but requires a full command line
1415  * for \c command_line_args including argv[0]. This is useful if the standard
1416  * library paths are relative to the binary.
1417  */
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  * \brief Flags that control how translation units are saved.
1426  *
1427  * The enumerators in this enumeration type are meant to be bitwise
1428  * ORed together to specify which options should be used when
1429  * saving the translation unit.
1430  */
1432  /**
1433  * \brief Used to indicate that no special saving options are needed.
1434  */
1436 };
1437 
1438 /**
1439  * \brief Returns the set of flags that is suitable for saving a translation
1440  * unit.
1441  *
1442  * The set of flags returned provide options for
1443  * \c clang_saveTranslationUnit() by default. The returned flag
1444  * set contains an unspecified set of options that save translation units with
1445  * the most commonly-requested data.
1446  */
1447 CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU);
1448 
1449 /**
1450  * \brief Describes the kind of error that occurred (if any) in a call to
1451  * \c clang_saveTranslationUnit().
1452  */
1454  /**
1455  * \brief Indicates that no error occurred while saving a translation unit.
1456  */
1458 
1459  /**
1460  * \brief Indicates that an unknown error occurred while attempting to save
1461  * the file.
1462  *
1463  * This error typically indicates that file I/O failed when attempting to
1464  * write the file.
1465  */
1467 
1468  /**
1469  * \brief Indicates that errors during translation prevented this attempt
1470  * to save the translation unit.
1471  *
1472  * Errors that prevent the translation unit from being saved can be
1473  * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic().
1474  */
1476 
1477  /**
1478  * \brief Indicates that the translation unit to be saved was somehow
1479  * invalid (e.g., NULL).
1480  */
1482 };
1483 
1484 /**
1485  * \brief Saves a translation unit into a serialized representation of
1486  * that translation unit on disk.
1487  *
1488  * Any translation unit that was parsed without error can be saved
1489  * into a file. The translation unit can then be deserialized into a
1490  * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
1491  * if it is an incomplete translation unit that corresponds to a
1492  * header, used as a precompiled header when parsing other translation
1493  * units.
1494  *
1495  * \param TU The translation unit to save.
1496  *
1497  * \param FileName The file to which the translation unit will be saved.
1498  *
1499  * \param options A bitmask of options that affects how the translation unit
1500  * is saved. This should be a bitwise OR of the
1501  * CXSaveTranslationUnit_XXX flags.
1502  *
1503  * \returns A value that will match one of the enumerators of the CXSaveError
1504  * enumeration. Zero (CXSaveError_None) indicates that the translation unit was
1505  * saved successfully, while a non-zero value indicates that a problem occurred.
1506  */
1507 CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
1508  const char *FileName,
1509  unsigned options);
1510 
1511 /**
1512  * \brief Suspend a translation unit in order to free memory associated with it.
1513  *
1514  * A suspended translation unit uses significantly less memory but on the other
1515  * side does not support any other calls than \c clang_reparseTranslationUnit
1516  * to resume it or \c clang_disposeTranslationUnit to dispose it completely.
1517  */
1518 CINDEX_LINKAGE unsigned clang_suspendTranslationUnit(CXTranslationUnit);
1519 
1520 /**
1521  * \brief Destroy the specified CXTranslationUnit object.
1522  */
1523 CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
1524 
1525 /**
1526  * \brief Flags that control the reparsing of translation units.
1527  *
1528  * The enumerators in this enumeration type are meant to be bitwise
1529  * ORed together to specify which options should be used when
1530  * reparsing the translation unit.
1531  */
1533  /**
1534  * \brief Used to indicate that no special reparsing options are needed.
1535  */
1537 };
1538 
1539 /**
1540  * \brief Returns the set of flags that is suitable for reparsing a translation
1541  * unit.
1542  *
1543  * The set of flags returned provide options for
1544  * \c clang_reparseTranslationUnit() by default. The returned flag
1545  * set contains an unspecified set of optimizations geared toward common uses
1546  * of reparsing. The set of optimizations enabled may change from one version
1547  * to the next.
1548  */
1549 CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
1550 
1551 /**
1552  * \brief Reparse the source files that produced this translation unit.
1553  *
1554  * This routine can be used to re-parse the source files that originally
1555  * created the given translation unit, for example because those source files
1556  * have changed (either on disk or as passed via \p unsaved_files). The
1557  * source code will be reparsed with the same command-line options as it
1558  * was originally parsed.
1559  *
1560  * Reparsing a translation unit invalidates all cursors and source locations
1561  * that refer into that translation unit. This makes reparsing a translation
1562  * unit semantically equivalent to destroying the translation unit and then
1563  * creating a new translation unit with the same command-line arguments.
1564  * However, it may be more efficient to reparse a translation
1565  * unit using this routine.
1566  *
1567  * \param TU The translation unit whose contents will be re-parsed. The
1568  * translation unit must originally have been built with
1569  * \c clang_createTranslationUnitFromSourceFile().
1570  *
1571  * \param num_unsaved_files The number of unsaved file entries in \p
1572  * unsaved_files.
1573  *
1574  * \param unsaved_files The files that have not yet been saved to disk
1575  * but may be required for parsing, including the contents of
1576  * those files. The contents and name of these files (as specified by
1577  * CXUnsavedFile) are copied when necessary, so the client only needs to
1578  * guarantee their validity until the call to this function returns.
1579  *
1580  * \param options A bitset of options composed of the flags in CXReparse_Flags.
1581  * The function \c clang_defaultReparseOptions() produces a default set of
1582  * options recommended for most uses, based on the translation unit.
1583  *
1584  * \returns 0 if the sources could be reparsed. A non-zero error code will be
1585  * returned if reparsing was impossible, such that the translation unit is
1586  * invalid. In such cases, the only valid call for \c TU is
1587  * \c clang_disposeTranslationUnit(TU). The error codes returned by this
1588  * routine are described by the \c CXErrorCode enum.
1589  */
1590 CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU,
1591  unsigned num_unsaved_files,
1592  struct CXUnsavedFile *unsaved_files,
1593  unsigned options);
1594 
1595 /**
1596  * \brief Categorizes how memory is being used by a translation unit.
1597  */
1616 
1619 };
1620 
1621 /**
1622  * \brief Returns the human-readable null-terminated C string that represents
1623  * the name of the memory category. This string should never be freed.
1624  */
1627 
1628 typedef struct CXTUResourceUsageEntry {
1629  /* \brief The memory usage category. */
1631  /* \brief Amount of resources used.
1632  The units will depend on the resource kind. */
1633  unsigned long amount;
1635 
1636 /**
1637  * \brief The memory usage of a CXTranslationUnit, broken into categories.
1638  */
1639 typedef struct CXTUResourceUsage {
1640  /* \brief Private data member, used for queries. */
1641  void *data;
1642 
1643  /* \brief The number of entries in the 'entries' array. */
1644  unsigned numEntries;
1645 
1646  /* \brief An array of key-value pairs, representing the breakdown of memory
1647  usage. */
1649 
1651 
1652 /**
1653  * \brief Return the memory usage of a translation unit. This object
1654  * should be released with clang_disposeCXTUResourceUsage().
1655  */
1657 
1659 
1660 /**
1661  * \brief Get target information for this translation unit.
1662  *
1663  * The CXTargetInfo object cannot outlive the CXTranslationUnit object.
1664  */
1665 CINDEX_LINKAGE CXTargetInfo
1666 clang_getTranslationUnitTargetInfo(CXTranslationUnit CTUnit);
1667 
1668 /**
1669  * \brief Destroy the CXTargetInfo object.
1670  */
1671 CINDEX_LINKAGE void
1672 clang_TargetInfo_dispose(CXTargetInfo Info);
1673 
1674 /**
1675  * \brief Get the normalized target triple as a string.
1676  *
1677  * Returns the empty string in case of any error.
1678  */
1680 clang_TargetInfo_getTriple(CXTargetInfo Info);
1681 
1682 /**
1683  * \brief Get the pointer width of the target in bits.
1684  *
1685  * Returns -1 in case of error.
1686  */
1687 CINDEX_LINKAGE int
1688 clang_TargetInfo_getPointerWidth(CXTargetInfo Info);
1689 
1690 /**
1691  * @}
1692  */
1693 
1694 /**
1695  * \brief Describes the kind of entity that a cursor refers to.
1696  */
1698  /* Declarations */
1699  /**
1700  * \brief A declaration whose specific kind is not exposed via this
1701  * interface.
1702  *
1703  * Unexposed declarations have the same operations as any other kind
1704  * of declaration; one can extract their location information,
1705  * spelling, find their definitions, etc. However, the specific kind
1706  * of the declaration is not reported.
1707  */
1709  /** \brief A C or C++ struct. */
1711  /** \brief A C or C++ union. */
1713  /** \brief A C++ class. */
1715  /** \brief An enumeration. */
1717  /**
1718  * \brief A field (in C) or non-static data member (in C++) in a
1719  * struct, union, or C++ class.
1720  */
1722  /** \brief An enumerator constant. */
1724  /** \brief A function. */
1726  /** \brief A variable. */
1728  /** \brief A function or method parameter. */
1730  /** \brief An Objective-C \@interface. */
1732  /** \brief An Objective-C \@interface for a category. */
1734  /** \brief An Objective-C \@protocol declaration. */
1736  /** \brief An Objective-C \@property declaration. */
1738  /** \brief An Objective-C instance variable. */
1740  /** \brief An Objective-C instance method. */
1742  /** \brief An Objective-C class method. */
1744  /** \brief An Objective-C \@implementation. */
1746  /** \brief An Objective-C \@implementation for a category. */
1748  /** \brief A typedef. */
1750  /** \brief A C++ class method. */
1752  /** \brief A C++ namespace. */
1754  /** \brief A linkage specification, e.g. 'extern "C"'. */
1756  /** \brief A C++ constructor. */
1758  /** \brief A C++ destructor. */
1760  /** \brief A C++ conversion function. */
1762  /** \brief A C++ template type parameter. */
1764  /** \brief A C++ non-type template parameter. */
1766  /** \brief A C++ template template parameter. */
1768  /** \brief A C++ function template. */
1770  /** \brief A C++ class template. */
1772  /** \brief A C++ class template partial specialization. */
1774  /** \brief A C++ namespace alias declaration. */
1776  /** \brief A C++ using directive. */
1778  /** \brief A C++ using declaration. */
1780  /** \brief A C++ alias declaration */
1782  /** \brief An Objective-C \@synthesize definition. */
1784  /** \brief An Objective-C \@dynamic definition. */
1786  /** \brief An access specifier. */
1788 
1791 
1792  /* References */
1793  CXCursor_FirstRef = 40, /* Decl references */
1797  /**
1798  * \brief A reference to a type declaration.
1799  *
1800  * A type reference occurs anywhere where a type is named but not
1801  * declared. For example, given:
1802  *
1803  * \code
1804  * typedef unsigned size_type;
1805  * size_type size;
1806  * \endcode
1807  *
1808  * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
1809  * while the type of the variable "size" is referenced. The cursor
1810  * referenced by the type of size is the typedef for size_type.
1811  */
1814  /**
1815  * \brief A reference to a class template, function template, template
1816  * template parameter, or class template partial specialization.
1817  */
1819  /**
1820  * \brief A reference to a namespace or namespace alias.
1821  */
1823  /**
1824  * \brief A reference to a member of a struct, union, or class that occurs in
1825  * some non-expression context, e.g., a designated initializer.
1826  */
1828  /**
1829  * \brief A reference to a labeled statement.
1830  *
1831  * This cursor kind is used to describe the jump to "start_over" in the
1832  * goto statement in the following example:
1833  *
1834  * \code
1835  * start_over:
1836  * ++counter;
1837  *
1838  * goto start_over;
1839  * \endcode
1840  *
1841  * A label reference cursor refers to a label statement.
1842  */
1844 
1845  /**
1846  * \brief A reference to a set of overloaded functions or function templates
1847  * that has not yet been resolved to a specific function or function template.
1848  *
1849  * An overloaded declaration reference cursor occurs in C++ templates where
1850  * a dependent name refers to a function. For example:
1851  *
1852  * \code
1853  * template<typename T> void swap(T&, T&);
1854  *
1855  * struct X { ... };
1856  * void swap(X&, X&);
1857  *
1858  * template<typename T>
1859  * void reverse(T* first, T* last) {
1860  * while (first < last - 1) {
1861  * swap(*first, *--last);
1862  * ++first;
1863  * }
1864  * }
1865  *
1866  * struct Y { };
1867  * void swap(Y&, Y&);
1868  * \endcode
1869  *
1870  * Here, the identifier "swap" is associated with an overloaded declaration
1871  * reference. In the template definition, "swap" refers to either of the two
1872  * "swap" functions declared above, so both results will be available. At
1873  * instantiation time, "swap" may also refer to other functions found via
1874  * argument-dependent lookup (e.g., the "swap" function at the end of the
1875  * example).
1876  *
1877  * The functions \c clang_getNumOverloadedDecls() and
1878  * \c clang_getOverloadedDecl() can be used to retrieve the definitions
1879  * referenced by this cursor.
1880  */
1882 
1883  /**
1884  * \brief A reference to a variable that occurs in some non-expression
1885  * context, e.g., a C++ lambda capture list.
1886  */
1888 
1890 
1891  /* Error conditions */
1898 
1899  /* Expressions */
1901 
1902  /**
1903  * \brief An expression whose specific kind is not exposed via this
1904  * interface.
1905  *
1906  * Unexposed expressions have the same operations as any other kind
1907  * of expression; one can extract their location information,
1908  * spelling, children, etc. However, the specific kind of the
1909  * expression is not reported.
1910  */
1912 
1913  /**
1914  * \brief An expression that refers to some value declaration, such
1915  * as a function, variable, or enumerator.
1916  */
1918 
1919  /**
1920  * \brief An expression that refers to a member of a struct, union,
1921  * class, Objective-C class, etc.
1922  */
1924 
1925  /** \brief An expression that calls a function. */
1927 
1928  /** \brief An expression that sends a message to an Objective-C
1929  object or class. */
1931 
1932  /** \brief An expression that represents a block literal. */
1934 
1935  /** \brief An integer literal.
1936  */
1938 
1939  /** \brief A floating point number literal.
1940  */
1942 
1943  /** \brief An imaginary number literal.
1944  */
1946 
1947  /** \brief A string literal.
1948  */
1950 
1951  /** \brief A character literal.
1952  */
1954 
1955  /** \brief A parenthesized expression, e.g. "(1)".
1956  *
1957  * This AST node is only formed if full location information is requested.
1958  */
1960 
1961  /** \brief This represents the unary-expression's (except sizeof and
1962  * alignof).
1963  */
1965 
1966  /** \brief [C99 6.5.2.1] Array Subscripting.
1967  */
1969 
1970  /** \brief A builtin binary operation expression such as "x + y" or
1971  * "x <= y".
1972  */
1974 
1975  /** \brief Compound assignment such as "+=".
1976  */
1978 
1979  /** \brief The ?: ternary operator.
1980  */
1982 
1983  /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++
1984  * (C++ [expr.cast]), which uses the syntax (Type)expr.
1985  *
1986  * For example: (int)f.
1987  */
1989 
1990  /** \brief [C99 6.5.2.5]
1991  */
1993 
1994  /** \brief Describes an C or C++ initializer list.
1995  */
1997 
1998  /** \brief The GNU address of label extension, representing &&label.
1999  */
2001 
2002  /** \brief This is the GNU Statement Expression extension: ({int X=4; X;})
2003  */
2005 
2006  /** \brief Represents a C11 generic selection.
2007  */
2009 
2010  /** \brief Implements the GNU __null extension, which is a name for a null
2011  * pointer constant that has integral type (e.g., int or long) and is the same
2012  * size and alignment as a pointer.
2013  *
2014  * The __null extension is typically only used by system headers, which define
2015  * NULL as __null in C++ rather than using 0 (which is an integer that may not
2016  * match the size of a pointer).
2017  */
2019 
2020  /** \brief C++'s static_cast<> expression.
2021  */
2023 
2024  /** \brief C++'s dynamic_cast<> expression.
2025  */
2027 
2028  /** \brief C++'s reinterpret_cast<> expression.
2029  */
2031 
2032  /** \brief C++'s const_cast<> expression.
2033  */
2035 
2036  /** \brief Represents an explicit C++ type conversion that uses "functional"
2037  * notion (C++ [expr.type.conv]).
2038  *
2039  * Example:
2040  * \code
2041  * x = int(0.5);
2042  * \endcode
2043  */
2045 
2046  /** \brief A C++ typeid expression (C++ [expr.typeid]).
2047  */
2049 
2050  /** \brief [C++ 2.13.5] C++ Boolean Literal.
2051  */
2053 
2054  /** \brief [C++0x 2.14.7] C++ Pointer Literal.
2055  */
2057 
2058  /** \brief Represents the "this" expression in C++
2059  */
2061 
2062  /** \brief [C++ 15] C++ Throw Expression.
2063  *
2064  * This handles 'throw' and 'throw' assignment-expression. When
2065  * assignment-expression isn't present, Op will be null.
2066  */
2068 
2069  /** \brief A new expression for memory allocation and constructor calls, e.g:
2070  * "new CXXNewExpr(foo)".
2071  */
2073 
2074  /** \brief A delete expression for memory deallocation and destructor calls,
2075  * e.g. "delete[] pArray".
2076  */
2078 
2079  /** \brief A unary expression. (noexcept, sizeof, or other traits)
2080  */
2082 
2083  /** \brief An Objective-C string literal i.e. @"foo".
2084  */
2086 
2087  /** \brief An Objective-C \@encode expression.
2088  */
2090 
2091  /** \brief An Objective-C \@selector expression.
2092  */
2094 
2095  /** \brief An Objective-C \@protocol expression.
2096  */
2098 
2099  /** \brief An Objective-C "bridged" cast expression, which casts between
2100  * Objective-C pointers and C pointers, transferring ownership in the process.
2101  *
2102  * \code
2103  * NSString *str = (__bridge_transfer NSString *)CFCreateString();
2104  * \endcode
2105  */
2107 
2108  /** \brief Represents a C++0x pack expansion that produces a sequence of
2109  * expressions.
2110  *
2111  * A pack expansion expression contains a pattern (which itself is an
2112  * expression) followed by an ellipsis. For example:
2113  *
2114  * \code
2115  * template<typename F, typename ...Types>
2116  * void forward(F f, Types &&...args) {
2117  * f(static_cast<Types&&>(args)...);
2118  * }
2119  * \endcode
2120  */
2122 
2123  /** \brief Represents an expression that computes the length of a parameter
2124  * pack.
2125  *
2126  * \code
2127  * template<typename ...Types>
2128  * struct count {
2129  * static const unsigned value = sizeof...(Types);
2130  * };
2131  * \endcode
2132  */
2134 
2135  /* \brief Represents a C++ lambda expression that produces a local function
2136  * object.
2137  *
2138  * \code
2139  * void abssort(float *x, unsigned N) {
2140  * std::sort(x, x + N,
2141  * [](float a, float b) {
2142  * return std::abs(a) < std::abs(b);
2143  * });
2144  * }
2145  * \endcode
2146  */
2148 
2149  /** \brief Objective-c Boolean Literal.
2150  */
2152 
2153  /** \brief Represents the "self" expression in an Objective-C method.
2154  */
2156 
2157  /** \brief OpenMP 4.0 [2.4, Array Section].
2158  */
2160 
2161  /** \brief Represents an @available(...) check.
2162  */
2164 
2166 
2167  /* Statements */
2169  /**
2170  * \brief A statement whose specific kind is not exposed via this
2171  * interface.
2172  *
2173  * Unexposed statements have the same operations as any other kind of
2174  * statement; one can extract their location information, spelling,
2175  * children, etc. However, the specific kind of the statement is not
2176  * reported.
2177  */
2179 
2180  /** \brief A labelled statement in a function.
2181  *
2182  * This cursor kind is used to describe the "start_over:" label statement in
2183  * the following example:
2184  *
2185  * \code
2186  * start_over:
2187  * ++counter;
2188  * \endcode
2189  *
2190  */
2192 
2193  /** \brief A group of statements like { stmt stmt }.
2194  *
2195  * This cursor kind is used to describe compound statements, e.g. function
2196  * bodies.
2197  */
2199 
2200  /** \brief A case statement.
2201  */
2203 
2204  /** \brief A default statement.
2205  */
2207 
2208  /** \brief An if statement
2209  */
2211 
2212  /** \brief A switch statement.
2213  */
2215 
2216  /** \brief A while statement.
2217  */
2219 
2220  /** \brief A do statement.
2221  */
2223 
2224  /** \brief A for statement.
2225  */
2227 
2228  /** \brief A goto statement.
2229  */
2231 
2232  /** \brief An indirect goto statement.
2233  */
2235 
2236  /** \brief A continue statement.
2237  */
2239 
2240  /** \brief A break statement.
2241  */
2243 
2244  /** \brief A return statement.
2245  */
2247 
2248  /** \brief A GCC inline assembly statement extension.
2249  */
2252 
2253  /** \brief Objective-C's overall \@try-\@catch-\@finally statement.
2254  */
2256 
2257  /** \brief Objective-C's \@catch statement.
2258  */
2260 
2261  /** \brief Objective-C's \@finally statement.
2262  */
2264 
2265  /** \brief Objective-C's \@throw statement.
2266  */
2268 
2269  /** \brief Objective-C's \@synchronized statement.
2270  */
2272 
2273  /** \brief Objective-C's autorelease pool statement.
2274  */
2276 
2277  /** \brief Objective-C's collection statement.
2278  */
2280 
2281  /** \brief C++'s catch statement.
2282  */
2284 
2285  /** \brief C++'s try statement.
2286  */
2288 
2289  /** \brief C++'s for (* : *) statement.
2290  */
2292 
2293  /** \brief Windows Structured Exception Handling's try statement.
2294  */
2296 
2297  /** \brief Windows Structured Exception Handling's except statement.
2298  */
2300 
2301  /** \brief Windows Structured Exception Handling's finally statement.
2302  */
2304 
2305  /** \brief A MS inline assembly statement extension.
2306  */
2308 
2309  /** \brief The null statement ";": C99 6.8.3p3.
2310  *
2311  * This cursor kind is used to describe the null statement.
2312  */
2314 
2315  /** \brief Adaptor class for mixing declarations with statements and
2316  * expressions.
2317  */
2319 
2320  /** \brief OpenMP parallel directive.
2321  */
2323 
2324  /** \brief OpenMP SIMD directive.
2325  */
2327 
2328  /** \brief OpenMP for directive.
2329  */
2331 
2332  /** \brief OpenMP sections directive.
2333  */
2335 
2336  /** \brief OpenMP section directive.
2337  */
2339 
2340  /** \brief OpenMP single directive.
2341  */
2343 
2344  /** \brief OpenMP parallel for directive.
2345  */
2347 
2348  /** \brief OpenMP parallel sections directive.
2349  */
2351 
2352  /** \brief OpenMP task directive.
2353  */
2355 
2356  /** \brief OpenMP master directive.
2357  */
2359 
2360  /** \brief OpenMP critical directive.
2361  */
2363 
2364  /** \brief OpenMP taskyield directive.
2365  */
2367 
2368  /** \brief OpenMP barrier directive.
2369  */
2371 
2372  /** \brief OpenMP taskwait directive.
2373  */
2375 
2376  /** \brief OpenMP flush directive.
2377  */
2379 
2380  /** \brief Windows Structured Exception Handling's leave statement.
2381  */
2383 
2384  /** \brief OpenMP ordered directive.
2385  */
2387 
2388  /** \brief OpenMP atomic directive.
2389  */
2391 
2392  /** \brief OpenMP for SIMD directive.
2393  */
2395 
2396  /** \brief OpenMP parallel for SIMD directive.
2397  */
2399 
2400  /** \brief OpenMP target directive.
2401  */
2403 
2404  /** \brief OpenMP teams directive.
2405  */
2407 
2408  /** \brief OpenMP taskgroup directive.
2409  */
2411 
2412  /** \brief OpenMP cancellation point directive.
2413  */
2415 
2416  /** \brief OpenMP cancel directive.
2417  */
2419 
2420  /** \brief OpenMP target data directive.
2421  */
2423 
2424  /** \brief OpenMP taskloop directive.
2425  */
2427 
2428  /** \brief OpenMP taskloop simd directive.
2429  */
2431 
2432  /** \brief OpenMP distribute directive.
2433  */
2435 
2436  /** \brief OpenMP target enter data directive.
2437  */
2439 
2440  /** \brief OpenMP target exit data directive.
2441  */
2443 
2444  /** \brief OpenMP target parallel directive.
2445  */
2447 
2448  /** \brief OpenMP target parallel for directive.
2449  */
2451 
2452  /** \brief OpenMP target update directive.
2453  */
2455 
2456  /** \brief OpenMP distribute parallel for directive.
2457  */
2459 
2460  /** \brief OpenMP distribute parallel for simd directive.
2461  */
2463 
2464  /** \brief OpenMP distribute simd directive.
2465  */
2467 
2468  /** \brief OpenMP target parallel for simd directive.
2469  */
2471 
2472  /** \brief OpenMP target simd directive.
2473  */
2475 
2476  /** \brief OpenMP teams distribute directive.
2477  */
2479 
2480  /** \brief OpenMP teams distribute simd directive.
2481  */
2483 
2484  /** \brief OpenMP teams distribute parallel for simd directive.
2485  */
2487 
2488  /** \brief OpenMP teams distribute parallel for directive.
2489  */
2491 
2492  /** \brief OpenMP target teams directive.
2493  */
2495 
2496  /** \brief OpenMP target teams distribute directive.
2497  */
2499 
2500  /** \brief OpenMP target teams distribute parallel for directive.
2501  */
2503 
2504  /** \brief OpenMP target teams distribute parallel for simd directive.
2505  */
2507 
2508  /** \brief OpenMP target teams distribute simd directive.
2509  */
2511 
2513 
2514  /**
2515  * \brief Cursor that represents the translation unit itself.
2516  *
2517  * The translation unit cursor exists primarily to act as the root
2518  * cursor for traversing the contents of a translation unit.
2519  */
2521 
2522  /* Attributes */
2524  /**
2525  * \brief An attribute whose specific kind is not exposed via this
2526  * interface.
2527  */
2529 
2550 
2551  /* Preprocessing */
2559 
2560  /* Extra Declarations */
2561  /**
2562  * \brief A module import declaration.
2563  */
2566  /**
2567  * \brief A static_assert or _Static_assert node
2568  */
2570  /**
2571  * \brief a friend declaration.
2572  */
2576 
2577  /**
2578  * \brief A code completion overload candidate.
2579  */
2581 };
2582 
2583 /**
2584  * \brief A cursor representing some element in the abstract syntax tree for
2585  * a translation unit.
2586  *
2587  * The cursor abstraction unifies the different kinds of entities in a
2588  * program--declaration, statements, expressions, references to declarations,
2589  * etc.--under a single "cursor" abstraction with a common set of operations.
2590  * Common operation for a cursor include: getting the physical location in
2591  * a source file where the cursor points, getting the name associated with a
2592  * cursor, and retrieving cursors for any child nodes of a particular cursor.
2593  *
2594  * Cursors can be produced in two specific ways.
2595  * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
2596  * from which one can use clang_visitChildren() to explore the rest of the
2597  * translation unit. clang_getCursor() maps from a physical source location
2598  * to the entity that resides at that location, allowing one to map from the
2599  * source code into the AST.
2600  */
2601 typedef struct {
2603  int xdata;
2604  const void *data[3];
2605 } CXCursor;
2606 
2607 /**
2608  * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
2609  *
2610  * @{
2611  */
2612 
2613 /**
2614  * \brief Retrieve the NULL cursor, which represents no entity.
2615  */
2617 
2618 /**
2619  * \brief Retrieve the cursor that represents the given translation unit.
2620  *
2621  * The translation unit cursor can be used to start traversing the
2622  * various declarations within the given translation unit.
2623  */
2625 
2626 /**
2627  * \brief Determine whether two cursors are equivalent.
2628  */
2630 
2631 /**
2632  * \brief Returns non-zero if \p cursor is null.
2633  */
2635 
2636 /**
2637  * \brief Compute a hash value for the given cursor.
2638  */
2640 
2641 /**
2642  * \brief Retrieve the kind of the given cursor.
2643  */
2645 
2646 /**
2647  * \brief Determine whether the given cursor kind represents a declaration.
2648  */
2650 
2651 /**
2652  * \brief Determine whether the given declaration is invalid.
2653  *
2654  * A declaration is invalid if it could not be parsed successfully.
2655  *
2656  * \returns non-zero if the cursor represents a declaration and it is
2657  * invalid, otherwise NULL.
2658  */
2660 
2661 /**
2662  * \brief Determine whether the given cursor kind represents a simple
2663  * reference.
2664  *
2665  * Note that other kinds of cursors (such as expressions) can also refer to
2666  * other cursors. Use clang_getCursorReferenced() to determine whether a
2667  * particular cursor refers to another entity.
2668  */
2670 
2671 /**
2672  * \brief Determine whether the given cursor kind represents an expression.
2673  */
2675 
2676 /**
2677  * \brief Determine whether the given cursor kind represents a statement.
2678  */
2680 
2681 /**
2682  * \brief Determine whether the given cursor kind represents an attribute.
2683  */
2685 
2686 /**
2687  * \brief Determine whether the given cursor has any attributes.
2688  */
2690 
2691 /**
2692  * \brief Determine whether the given cursor kind represents an invalid
2693  * cursor.
2694  */
2696 
2697 /**
2698  * \brief Determine whether the given cursor kind represents a translation
2699  * unit.
2700  */
2702 
2703 /***
2704  * \brief Determine whether the given cursor represents a preprocessing
2705  * element, such as a preprocessor directive or macro instantiation.
2706  */
2708 
2709 /***
2710  * \brief Determine whether the given cursor represents a currently
2711  * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
2712  */
2714 
2715 /**
2716  * \brief Describe the linkage of the entity referred to by a cursor.
2717  */
2719  /** \brief This value indicates that no linkage information is available
2720  * for a provided CXCursor. */
2722  /**
2723  * \brief This is the linkage for variables, parameters, and so on that
2724  * have automatic storage. This covers normal (non-extern) local variables.
2725  */
2727  /** \brief This is the linkage for static variables and static functions. */
2729  /** \brief This is the linkage for entities with external linkage that live
2730  * in C++ anonymous namespaces.*/
2732  /** \brief This is the linkage for entities with true, external linkage. */
2734 };
2735 
2736 /**
2737  * \brief Determine the linkage of the entity referred to by a given cursor.
2738  */
2740 
2742  /** \brief This value indicates that no visibility information is available
2743  * for a provided CXCursor. */
2745 
2746  /** \brief Symbol not seen by the linker. */
2748  /** \brief Symbol seen by the linker but resolves to a symbol inside this object. */
2750  /** \brief Symbol seen by the linker and acts like a normal symbol. */
2752 };
2753 
2754 /**
2755  * \brief Describe the visibility of the entity referred to by a cursor.
2756  *
2757  * This returns the default visibility if not explicitly specified by
2758  * a visibility attribute. The default visibility may be changed by
2759  * commandline arguments.
2760  *
2761  * \param cursor The cursor to query.
2762  *
2763  * \returns The visibility of the cursor.
2764  */
2766 
2767 /**
2768  * \brief Determine the availability of the entity that this cursor refers to,
2769  * taking the current target platform into account.
2770  *
2771  * \param cursor The cursor to query.
2772  *
2773  * \returns The availability of the cursor.
2774  */
2777 
2778 /**
2779  * Describes the availability of a given entity on a particular platform, e.g.,
2780  * a particular class might only be available on Mac OS 10.7 or newer.
2781  */
2782 typedef struct CXPlatformAvailability {
2783  /**
2784  * \brief A string that describes the platform for which this structure
2785  * provides availability information.
2786  *
2787  * Possible values are "ios" or "macos".
2788  */
2790  /**
2791  * \brief The version number in which this entity was introduced.
2792  */
2794  /**
2795  * \brief The version number in which this entity was deprecated (but is
2796  * still available).
2797  */
2799  /**
2800  * \brief The version number in which this entity was obsoleted, and therefore
2801  * is no longer available.
2802  */
2804  /**
2805  * \brief Whether the entity is unconditionally unavailable on this platform.
2806  */
2808  /**
2809  * \brief An optional message to provide to a user of this API, e.g., to
2810  * suggest replacement APIs.
2811  */
2814 
2815 /**
2816  * \brief Determine the availability of the entity that this cursor refers to
2817  * on any platforms for which availability information is known.
2818  *
2819  * \param cursor The cursor to query.
2820  *
2821  * \param always_deprecated If non-NULL, will be set to indicate whether the
2822  * entity is deprecated on all platforms.
2823  *
2824  * \param deprecated_message If non-NULL, will be set to the message text
2825  * provided along with the unconditional deprecation of this entity. The client
2826  * is responsible for deallocating this string.
2827  *
2828  * \param always_unavailable If non-NULL, will be set to indicate whether the
2829  * entity is unavailable on all platforms.
2830  *
2831  * \param unavailable_message If non-NULL, will be set to the message text
2832  * provided along with the unconditional unavailability of this entity. The
2833  * client is responsible for deallocating this string.
2834  *
2835  * \param availability If non-NULL, an array of CXPlatformAvailability instances
2836  * that will be populated with platform availability information, up to either
2837  * the number of platforms for which availability information is available (as
2838  * returned by this function) or \c availability_size, whichever is smaller.
2839  *
2840  * \param availability_size The number of elements available in the
2841  * \c availability array.
2842  *
2843  * \returns The number of platforms (N) for which availability information is
2844  * available (which is unrelated to \c availability_size).
2845  *
2846  * Note that the client is responsible for calling
2847  * \c clang_disposeCXPlatformAvailability to free each of the
2848  * platform-availability structures returned. There are
2849  * \c min(N, availability_size) such structures.
2850  */
2851 CINDEX_LINKAGE int
2853  int *always_deprecated,
2854  CXString *deprecated_message,
2855  int *always_unavailable,
2856  CXString *unavailable_message,
2857  CXPlatformAvailability *availability,
2858  int availability_size);
2859 
2860 /**
2861  * \brief Free the memory associated with a \c CXPlatformAvailability structure.
2862  */
2863 CINDEX_LINKAGE void
2865 
2866 /**
2867  * \brief Describe the "language" of the entity referred to by a cursor.
2868  */
2874 };
2875 
2876 /**
2877  * \brief Determine the "language" of the entity referred to by a given cursor.
2878  */
2880 
2881 /**
2882  * \brief Describe the "thread-local storage (TLS) kind" of the declaration
2883  * referred to by a cursor.
2884  */
2889 };
2890 
2891 /**
2892  * \brief Determine the "thread-local storage (TLS) kind" of the declaration
2893  * referred to by a cursor.
2894  */
2896 
2897 /**
2898  * \brief Returns the translation unit that a cursor originated from.
2899  */
2901 
2902 /**
2903  * \brief A fast container representing a set of CXCursors.
2904  */
2905 typedef struct CXCursorSetImpl *CXCursorSet;
2906 
2907 /**
2908  * \brief Creates an empty CXCursorSet.
2909  */
2910 CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void);
2911 
2912 /**
2913  * \brief Disposes a CXCursorSet and releases its associated memory.
2914  */
2915 CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset);
2916 
2917 /**
2918  * \brief Queries a CXCursorSet to see if it contains a specific CXCursor.
2919  *
2920  * \returns non-zero if the set contains the specified cursor.
2921 */
2922 CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset,
2923  CXCursor cursor);
2924 
2925 /**
2926  * \brief Inserts a CXCursor into a CXCursorSet.
2927  *
2928  * \returns zero if the CXCursor was already in the set, and non-zero otherwise.
2929 */
2930 CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset,
2931  CXCursor cursor);
2932 
2933 /**
2934  * \brief Determine the semantic parent of the given cursor.
2935  *
2936  * The semantic parent of a cursor is the cursor that semantically contains
2937  * the given \p cursor. For many declarations, the lexical and semantic parents
2938  * are equivalent (the lexical parent is returned by
2939  * \c clang_getCursorLexicalParent()). They diverge when declarations or
2940  * definitions are provided out-of-line. For example:
2941  *
2942  * \code
2943  * class C {
2944  * void f();
2945  * };
2946  *
2947  * void C::f() { }
2948  * \endcode
2949  *
2950  * In the out-of-line definition of \c C::f, the semantic parent is
2951  * the class \c C, of which this function is a member. The lexical parent is
2952  * the place where the declaration actually occurs in the source code; in this
2953  * case, the definition occurs in the translation unit. In general, the
2954  * lexical parent for a given entity can change without affecting the semantics
2955  * of the program, and the lexical parent of different declarations of the
2956  * same entity may be different. Changing the semantic parent of a declaration,
2957  * on the other hand, can have a major impact on semantics, and redeclarations
2958  * of a particular entity should all have the same semantic context.
2959  *
2960  * In the example above, both declarations of \c C::f have \c C as their
2961  * semantic context, while the lexical context of the first \c C::f is \c C
2962  * and the lexical context of the second \c C::f is the translation unit.
2963  *
2964  * For global declarations, the semantic parent is the translation unit.
2965  */
2967 
2968 /**
2969  * \brief Determine the lexical parent of the given cursor.
2970  *
2971  * The lexical parent of a cursor is the cursor in which the given \p cursor
2972  * was actually written. For many declarations, the lexical and semantic parents
2973  * are equivalent (the semantic parent is returned by
2974  * \c clang_getCursorSemanticParent()). They diverge when declarations or
2975  * definitions are provided out-of-line. For example:
2976  *
2977  * \code
2978  * class C {
2979  * void f();
2980  * };
2981  *
2982  * void C::f() { }
2983  * \endcode
2984  *
2985  * In the out-of-line definition of \c C::f, the semantic parent is
2986  * the class \c C, of which this function is a member. The lexical parent is
2987  * the place where the declaration actually occurs in the source code; in this
2988  * case, the definition occurs in the translation unit. In general, the
2989  * lexical parent for a given entity can change without affecting the semantics
2990  * of the program, and the lexical parent of different declarations of the
2991  * same entity may be different. Changing the semantic parent of a declaration,
2992  * on the other hand, can have a major impact on semantics, and redeclarations
2993  * of a particular entity should all have the same semantic context.
2994  *
2995  * In the example above, both declarations of \c C::f have \c C as their
2996  * semantic context, while the lexical context of the first \c C::f is \c C
2997  * and the lexical context of the second \c C::f is the translation unit.
2998  *
2999  * For declarations written in the global scope, the lexical parent is
3000  * the translation unit.
3001  */
3003 
3004 /**
3005  * \brief Determine the set of methods that are overridden by the given
3006  * method.
3007  *
3008  * In both Objective-C and C++, a method (aka virtual member function,
3009  * in C++) can override a virtual method in a base class. For
3010  * Objective-C, a method is said to override any method in the class's
3011  * base class, its protocols, or its categories' protocols, that has the same
3012  * selector and is of the same kind (class or instance).
3013  * If no such method exists, the search continues to the class's superclass,
3014  * its protocols, and its categories, and so on. A method from an Objective-C
3015  * implementation is considered to override the same methods as its
3016  * corresponding method in the interface.
3017  *
3018  * For C++, a virtual member function overrides any virtual member
3019  * function with the same signature that occurs in its base
3020  * classes. With multiple inheritance, a virtual member function can
3021  * override several virtual member functions coming from different
3022  * base classes.
3023  *
3024  * In all cases, this function determines the immediate overridden
3025  * method, rather than all of the overridden methods. For example, if
3026  * a method is originally declared in a class A, then overridden in B
3027  * (which in inherits from A) and also in C (which inherited from B),
3028  * then the only overridden method returned from this function when
3029  * invoked on C's method will be B's method. The client may then
3030  * invoke this function again, given the previously-found overridden
3031  * methods, to map out the complete method-override set.
3032  *
3033  * \param cursor A cursor representing an Objective-C or C++
3034  * method. This routine will compute the set of methods that this
3035  * method overrides.
3036  *
3037  * \param overridden A pointer whose pointee will be replaced with a
3038  * pointer to an array of cursors, representing the set of overridden
3039  * methods. If there are no overridden methods, the pointee will be
3040  * set to NULL. The pointee must be freed via a call to
3041  * \c clang_disposeOverriddenCursors().
3042  *
3043  * \param num_overridden A pointer to the number of overridden
3044  * functions, will be set to the number of overridden functions in the
3045  * array pointed to by \p overridden.
3046  */
3048  CXCursor **overridden,
3049  unsigned *num_overridden);
3050 
3051 /**
3052  * \brief Free the set of overridden cursors returned by \c
3053  * clang_getOverriddenCursors().
3054  */
3056 
3057 /**
3058  * \brief Retrieve the file that is included by the given inclusion directive
3059  * cursor.
3060  */
3062 
3063 /**
3064  * @}
3065  */
3066 
3067 /**
3068  * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
3069  *
3070  * Cursors represent a location within the Abstract Syntax Tree (AST). These
3071  * routines help map between cursors and the physical locations where the
3072  * described entities occur in the source code. The mapping is provided in
3073  * both directions, so one can map from source code to the AST and back.
3074  *
3075  * @{
3076  */
3077 
3078 /**
3079  * \brief Map a source location to the cursor that describes the entity at that
3080  * location in the source code.
3081  *
3082  * clang_getCursor() maps an arbitrary source location within a translation
3083  * unit down to the most specific cursor that describes the entity at that
3084  * location. For example, given an expression \c x + y, invoking
3085  * clang_getCursor() with a source location pointing to "x" will return the
3086  * cursor for "x"; similarly for "y". If the cursor points anywhere between
3087  * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
3088  * will return a cursor referring to the "+" expression.
3089  *
3090  * \returns a cursor representing the entity at the given source location, or
3091  * a NULL cursor if no such entity can be found.
3092  */
3094 
3095 /**
3096  * \brief Retrieve the physical location of the source constructor referenced
3097  * by the given cursor.
3098  *
3099  * The location of a declaration is typically the location of the name of that
3100  * declaration, where the name of that declaration would occur if it is
3101  * unnamed, or some keyword that introduces that particular declaration.
3102  * The location of a reference is where that reference occurs within the
3103  * source code.
3104  */
3106 
3107 /**
3108  * \brief Retrieve the physical extent of the source construct referenced by
3109  * the given cursor.
3110  *
3111  * The extent of a cursor starts with the file/line/column pointing at the
3112  * first character within the source construct that the cursor refers to and
3113  * ends with the last character within that source construct. For a
3114  * declaration, the extent covers the declaration itself. For a reference,
3115  * the extent covers the location of the reference (e.g., where the referenced
3116  * entity was actually used).
3117  */
3119 
3120 /**
3121  * @}
3122  */
3123 
3124 /**
3125  * \defgroup CINDEX_TYPES Type information for CXCursors
3126  *
3127  * @{
3128  */
3129 
3130 /**
3131  * \brief Describes the kind of type
3132  */
3134  /**
3135  * \brief Represents an invalid type (e.g., where no type is available).
3136  */
3138 
3139  /**
3140  * \brief A type whose specific kind is not exposed via this
3141  * interface.
3142  */
3144 
3145  /* Builtin types */
3179 
3199 
3200  /**
3201  * \brief Represents a type that was referred to using an elaborated type keyword.
3202  *
3203  * E.g., struct S, or via a qualified name, e.g., N::M::type, or both.
3204  */
3206 
3207  /* OpenCL PipeType. */
3209 
3210  /* OpenCL builtin types. */
3251 };
3252 
3253 /**
3254  * \brief Describes the calling convention of a function type
3255  */
3268  /* Alias for compatibility with older versions of API. */
3275 
3278 };
3279 
3280 /**
3281  * \brief The type of an element in the abstract syntax tree.
3282  *
3283  */
3284 typedef struct {
3286  void *data[2];
3287 } CXType;
3288 
3289 /**
3290  * \brief Retrieve the type of a CXCursor (if any).
3291  */
3293 
3294 /**
3295  * \brief Pretty-print the underlying type using the rules of the
3296  * language of the translation unit from which it came.
3297  *
3298  * If the type is invalid, an empty string is returned.
3299  */
3301 
3302 /**
3303  * \brief Retrieve the underlying type of a typedef declaration.
3304  *
3305  * If the cursor does not reference a typedef declaration, an invalid type is
3306  * returned.
3307  */
3309 
3310 /**
3311  * \brief Retrieve the integer type of an enum declaration.
3312  *
3313  * If the cursor does not reference an enum declaration, an invalid type is
3314  * returned.
3315  */
3317 
3318 /**
3319  * \brief Retrieve the integer value of an enum constant declaration as a signed
3320  * long long.
3321  *
3322  * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned.
3323  * Since this is also potentially a valid constant value, the kind of the cursor
3324  * must be verified before calling this function.
3325  */
3327 
3328 /**
3329  * \brief Retrieve the integer value of an enum constant declaration as an unsigned
3330  * long long.
3331  *
3332  * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned.
3333  * Since this is also potentially a valid constant value, the kind of the cursor
3334  * must be verified before calling this function.
3335  */
3337 
3338 /**
3339  * \brief Retrieve the bit width of a bit field declaration as an integer.
3340  *
3341  * If a cursor that is not a bit field declaration is passed in, -1 is returned.
3342  */
3344 
3345 /**
3346  * \brief Retrieve the number of non-variadic arguments associated with a given
3347  * cursor.
3348  *
3349  * The number of arguments can be determined for calls as well as for
3350  * declarations of functions or methods. For other cursors -1 is returned.
3351  */
3353 
3354 /**
3355  * \brief Retrieve the argument cursor of a function or method.
3356  *
3357  * The argument cursor can be determined for calls as well as for declarations
3358  * of functions or methods. For other cursors and for invalid indices, an
3359  * invalid cursor is returned.
3360  */
3362 
3363 /**
3364  * \brief Describes the kind of a template argument.
3365  *
3366  * See the definition of llvm::clang::TemplateArgument::ArgKind for full
3367  * element descriptions.
3368  */
3379  /* Indicates an error case, preventing the kind from being deduced. */
3381 };
3382 
3383 /**
3384  *\brief Returns the number of template args of a function decl representing a
3385  * template specialization.
3386  *
3387  * If the argument cursor cannot be converted into a template function
3388  * declaration, -1 is returned.
3389  *
3390  * For example, for the following declaration and specialization:
3391  * template <typename T, int kInt, bool kBool>
3392  * void foo() { ... }
3393  *
3394  * template <>
3395  * void foo<float, -7, true>();
3396  *
3397  * The value 3 would be returned from this call.
3398  */
3400 
3401 /**
3402  * \brief Retrieve the kind of the I'th template argument of the CXCursor C.
3403  *
3404  * If the argument CXCursor does not represent a FunctionDecl, an invalid
3405  * template argument kind is returned.
3406  *
3407  * For example, for the following declaration and specialization:
3408  * template <typename T, int kInt, bool kBool>
3409  * void foo() { ... }
3410  *
3411  * template <>
3412  * void foo<float, -7, true>();
3413  *
3414  * For I = 0, 1, and 2, Type, Integral, and Integral will be returned,
3415  * respectively.
3416  */
3418  CXCursor C, unsigned I);
3419 
3420 /**
3421  * \brief Retrieve a CXType representing the type of a TemplateArgument of a
3422  * function decl representing a template specialization.
3423  *
3424  * If the argument CXCursor does not represent a FunctionDecl whose I'th
3425  * template argument has a kind of CXTemplateArgKind_Integral, an invalid type
3426  * is returned.
3427  *
3428  * For example, for the following declaration and specialization:
3429  * template <typename T, int kInt, bool kBool>
3430  * void foo() { ... }
3431  *
3432  * template <>
3433  * void foo<float, -7, true>();
3434  *
3435  * If called with I = 0, "float", will be returned.
3436  * Invalid types will be returned for I == 1 or 2.
3437  */
3439  unsigned I);
3440 
3441 /**
3442  * \brief Retrieve the value of an Integral TemplateArgument (of a function
3443  * decl representing a template specialization) as a signed long long.
3444  *
3445  * It is undefined to call this function on a CXCursor that does not represent a
3446  * FunctionDecl or whose I'th template argument is not an integral value.
3447  *
3448  * For example, for the following declaration and specialization:
3449  * template <typename T, int kInt, bool kBool>
3450  * void foo() { ... }
3451  *
3452  * template <>
3453  * void foo<float, -7, true>();
3454  *
3455  * If called with I = 1 or 2, -7 or true will be returned, respectively.
3456  * For I == 0, this function's behavior is undefined.
3457  */
3459  unsigned I);
3460 
3461 /**
3462  * \brief Retrieve the value of an Integral TemplateArgument (of a function
3463  * decl representing a template specialization) as an unsigned long long.
3464  *
3465  * It is undefined to call this function on a CXCursor that does not represent a
3466  * FunctionDecl or whose I'th template argument is not an integral value.
3467  *
3468  * For example, for the following declaration and specialization:
3469  * template <typename T, int kInt, bool kBool>
3470  * void foo() { ... }
3471  *
3472  * template <>
3473  * void foo<float, 2147483649, true>();
3474  *
3475  * If called with I = 1 or 2, 2147483649 or true will be returned, respectively.
3476  * For I == 0, this function's behavior is undefined.
3477  */
3479  CXCursor C, unsigned I);
3480 
3481 /**
3482  * \brief Determine whether two CXTypes represent the same type.
3483  *
3484  * \returns non-zero if the CXTypes represent the same type and
3485  * zero otherwise.
3486  */
3488 
3489 /**
3490  * \brief Return the canonical type for a CXType.
3491  *
3492  * Clang's type system explicitly models typedefs and all the ways
3493  * a specific type can be represented. The canonical type is the underlying
3494  * type with all the "sugar" removed. For example, if 'T' is a typedef
3495  * for 'int', the canonical type for 'T' would be 'int'.
3496  */
3498 
3499 /**
3500  * \brief Determine whether a CXType has the "const" qualifier set,
3501  * without looking through typedefs that may have added "const" at a
3502  * different level.
3503  */
3505 
3506 /**
3507  * \brief Determine whether a CXCursor that is a macro, is
3508  * function like.
3509  */
3511 
3512 /**
3513  * \brief Determine whether a CXCursor that is a macro, is a
3514  * builtin one.
3515  */
3517 
3518 /**
3519  * \brief Determine whether a CXCursor that is a function declaration, is an
3520  * inline declaration.
3521  */
3523 
3524 /**
3525  * \brief Determine whether a CXType has the "volatile" qualifier set,
3526  * without looking through typedefs that may have added "volatile" at
3527  * a different level.
3528  */
3530 
3531 /**
3532  * \brief Determine whether a CXType has the "restrict" qualifier set,
3533  * without looking through typedefs that may have added "restrict" at a
3534  * different level.
3535  */
3537 
3538 /**
3539  * \brief Returns the address space of the given type.
3540  */
3542 
3543 /**
3544  * \brief Returns the typedef name of the given type.
3545  */
3547 
3548 /**
3549  * \brief For pointer types, returns the type of the pointee.
3550  */
3552 
3553 /**
3554  * \brief Return the cursor for the declaration of the given type.
3555  */
3557 
3558 /**
3559  * Returns the Objective-C type encoding for the specified declaration.
3560  */
3562 
3563 /**
3564  * Returns the Objective-C type encoding for the specified CXType.
3565  */
3567 
3568 /**
3569  * \brief Retrieve the spelling of a given CXTypeKind.
3570  */
3572 
3573 /**
3574  * \brief Retrieve the calling convention associated with a function type.
3575  *
3576  * If a non-function type is passed in, CXCallingConv_Invalid is returned.
3577  */
3579 
3580 /**
3581  * \brief Retrieve the return type associated with a function type.
3582  *
3583  * If a non-function type is passed in, an invalid type is returned.
3584  */
3586 
3587 /**
3588  * \brief Retrieve the exception specification type associated with a function type.
3589  *
3590  * If a non-function type is passed in, an error code of -1 is returned.
3591  */
3593 
3594 /**
3595  * \brief Retrieve the number of non-variadic parameters associated with a
3596  * function type.
3597  *
3598  * If a non-function type is passed in, -1 is returned.
3599  */
3601 
3602 /**
3603  * \brief Retrieve the type of a parameter of a function type.
3604  *
3605  * If a non-function type is passed in or the function does not have enough
3606  * parameters, an invalid type is returned.
3607  */
3609 
3610 /**
3611  * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise.
3612  */
3614 
3615 /**
3616  * \brief Retrieve the return type associated with a given cursor.
3617  *
3618  * This only returns a valid type if the cursor refers to a function or method.
3619  */
3621 
3622 /**
3623  * \brief Retrieve the exception specification type associated with a given cursor.
3624  *
3625  * This only returns a valid result if the cursor refers to a function or method.
3626  */
3628 
3629 /**
3630  * \brief Return 1 if the CXType is a POD (plain old data) type, and 0
3631  * otherwise.
3632  */
3634 
3635 /**
3636  * \brief Return the element type of an array, complex, or vector type.
3637  *
3638  * If a type is passed in that is not an array, complex, or vector type,
3639  * an invalid type is returned.
3640  */
3642 
3643 /**
3644  * \brief Return the number of elements of an array or vector type.
3645  *
3646  * If a type is passed in that is not an array or vector type,
3647  * -1 is returned.
3648  */
3650 
3651 /**
3652  * \brief Return the element type of an array type.
3653  *
3654  * If a non-array type is passed in, an invalid type is returned.
3655  */
3657 
3658 /**
3659  * \brief Return the array size of a constant array.
3660  *
3661  * If a non-array type is passed in, -1 is returned.
3662  */
3664 
3665 /**
3666  * \brief Retrieve the type named by the qualified-id.
3667  *
3668  * If a non-elaborated type is passed in, an invalid type is returned.
3669  */
3671 
3672 /**
3673  * \brief Determine if a typedef is 'transparent' tag.
3674  *
3675  * A typedef is considered 'transparent' if it shares a name and spelling
3676  * location with its underlying tag type, as is the case with the NS_ENUM macro.
3677  *
3678  * \returns non-zero if transparent and zero otherwise.
3679  */
3681 
3682 /**
3683  * \brief List the possible error codes for \c clang_Type_getSizeOf,
3684  * \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and
3685  * \c clang_Cursor_getOffsetOf.
3686  *
3687  * A value of this enumeration type can be returned if the target type is not
3688  * a valid argument to sizeof, alignof or offsetof.
3689  */
3691  /**
3692  * \brief Type is of kind CXType_Invalid.
3693  */
3695  /**
3696  * \brief The type is an incomplete Type.
3697  */
3699  /**
3700  * \brief The type is a dependent Type.
3701  */
3703  /**
3704  * \brief The type is not a constant size type.
3705  */
3707  /**
3708  * \brief The Field name is not valid for this record.
3709  */
3711 };
3712 
3713 /**
3714  * \brief Return the alignment of a type in bytes as per C++[expr.alignof]
3715  * standard.
3716  *
3717  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3718  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3719  * is returned.
3720  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3721  * returned.
3722  * If the type declaration is not a constant size type,
3723  * CXTypeLayoutError_NotConstantSize is returned.
3724  */
3726 
3727 /**
3728  * \brief Return the class type of an member pointer type.
3729  *
3730  * If a non-member-pointer type is passed in, an invalid type is returned.
3731  */
3733 
3734 /**
3735  * \brief Return the size of a type in bytes as per C++[expr.sizeof] standard.
3736  *
3737  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3738  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3739  * is returned.
3740  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3741  * returned.
3742  */
3744 
3745 /**
3746  * \brief Return the offset of a field named S in a record of type T in bits
3747  * as it would be returned by __offsetof__ as per C++11[18.2p4]
3748  *
3749  * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid
3750  * is returned.
3751  * If the field's type declaration is an incomplete type,
3752  * CXTypeLayoutError_Incomplete is returned.
3753  * If the field's type declaration is a dependent type,
3754  * CXTypeLayoutError_Dependent is returned.
3755  * If the field's name S is not found,
3756  * CXTypeLayoutError_InvalidFieldName is returned.
3757  */
3758 CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S);
3759 
3760 /**
3761  * \brief Return the offset of the field represented by the Cursor.
3762  *
3763  * If the cursor is not a field declaration, -1 is returned.
3764  * If the cursor semantic parent is not a record field declaration,
3765  * CXTypeLayoutError_Invalid is returned.
3766  * If the field's type declaration is an incomplete type,
3767  * CXTypeLayoutError_Incomplete is returned.
3768  * If the field's type declaration is a dependent type,
3769  * CXTypeLayoutError_Dependent is returned.
3770  * If the field's name S is not found,
3771  * CXTypeLayoutError_InvalidFieldName is returned.
3772  */
3774 
3775 /**
3776  * \brief Determine whether the given cursor represents an anonymous record
3777  * declaration.
3778  */
3780 
3782  /** \brief No ref-qualifier was provided. */
3784  /** \brief An lvalue ref-qualifier was provided (\c &). */
3786  /** \brief An rvalue ref-qualifier was provided (\c &&). */
3788 };
3789 
3790 /**
3791  * \brief Returns the number of template arguments for given template
3792  * specialization, or -1 if type \c T is not a template specialization.
3793  */
3795 
3796 /**
3797  * \brief Returns the type template argument of a template class specialization
3798  * at given index.
3799  *
3800  * This function only returns template type arguments and does not handle
3801  * template template arguments or variadic packs.
3802  */
3804 
3805 /**
3806  * \brief Retrieve the ref-qualifier kind of a function or method.
3807  *
3808  * The ref-qualifier is returned for C++ functions or methods. For other types
3809  * or non-C++ declarations, CXRefQualifier_None is returned.
3810  */
3812 
3813 /**
3814  * \brief Returns non-zero if the cursor specifies a Record member that is a
3815  * bitfield.
3816  */
3818 
3819 /**
3820  * \brief Returns 1 if the base class specified by the cursor with kind
3821  * CX_CXXBaseSpecifier is virtual.
3822  */
3824 
3825 /**
3826  * \brief Represents the C++ access control level to a base class for a
3827  * cursor with kind CX_CXXBaseSpecifier.
3828  */
3834 };
3835 
3836 /**
3837  * \brief Returns the access control level for the referenced object.
3838  *
3839  * If the cursor refers to a C++ declaration, its access control level within its
3840  * parent scope is returned. Otherwise, if the cursor refers to a base specifier or
3841  * access specifier, the specifier itself is returned.
3842  */
3844 
3845 /**
3846  * \brief Represents the storage classes as declared in the source. CX_SC_Invalid
3847  * was added for the case that the passed cursor in not a declaration.
3848  */
3858 };
3859 
3860 /**
3861  * \brief Returns the storage class for a function or variable declaration.
3862  *
3863  * If the passed in Cursor is not a function or variable declaration,
3864  * CX_SC_Invalid is returned else the storage class.
3865  */
3867 
3868 /**
3869  * \brief Determine the number of overloaded declarations referenced by a
3870  * \c CXCursor_OverloadedDeclRef cursor.
3871  *
3872  * \param cursor The cursor whose overloaded declarations are being queried.
3873  *
3874  * \returns The number of overloaded declarations referenced by \c cursor. If it
3875  * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0.
3876  */
3878 
3879 /**
3880  * \brief Retrieve a cursor for one of the overloaded declarations referenced
3881  * by a \c CXCursor_OverloadedDeclRef cursor.
3882  *
3883  * \param cursor The cursor whose overloaded declarations are being queried.
3884  *
3885  * \param index The zero-based index into the set of overloaded declarations in
3886  * the cursor.
3887  *
3888  * \returns A cursor representing the declaration referenced by the given
3889  * \c cursor at the specified \c index. If the cursor does not have an
3890  * associated set of overloaded declarations, or if the index is out of bounds,
3891  * returns \c clang_getNullCursor();
3892  */
3894  unsigned index);
3895 
3896 /**
3897  * @}
3898  */
3899 
3900 /**
3901  * \defgroup CINDEX_ATTRIBUTES Information for attributes
3902  *
3903  * @{
3904  */
3905 
3906 /**
3907  * \brief For cursors representing an iboutletcollection attribute,
3908  * this function returns the collection element type.
3909  *
3910  */
3912 
3913 /**
3914  * @}
3915  */
3916 
3917 /**
3918  * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
3919  *
3920  * These routines provide the ability to traverse the abstract syntax tree
3921  * using cursors.
3922  *
3923  * @{
3924  */
3925 
3926 /**
3927  * \brief Describes how the traversal of the children of a particular
3928  * cursor should proceed after visiting a particular child cursor.
3929  *
3930  * A value of this enumeration type should be returned by each
3931  * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
3932  */
3934  /**
3935  * \brief Terminates the cursor traversal.
3936  */
3938  /**
3939  * \brief Continues the cursor traversal with the next sibling of
3940  * the cursor just visited, without visiting its children.
3941  */
3943  /**
3944  * \brief Recursively traverse the children of this cursor, using
3945  * the same visitor and client data.
3946  */
3948 };
3949 
3950 /**
3951  * \brief Visitor invoked for each cursor found by a traversal.
3952  *
3953  * This visitor function will be invoked for each cursor found by
3954  * clang_visitCursorChildren(). Its first argument is the cursor being
3955  * visited, its second argument is the parent visitor for that cursor,
3956  * and its third argument is the client data provided to
3957  * clang_visitCursorChildren().
3958  *
3959  * The visitor should return one of the \c CXChildVisitResult values
3960  * to direct clang_visitCursorChildren().
3961  */
3963  CXCursor parent,
3964  CXClientData client_data);
3965 
3966 /**
3967  * \brief Visit the children of a particular cursor.
3968  *
3969  * This function visits all the direct children of the given cursor,
3970  * invoking the given \p visitor function with the cursors of each
3971  * visited child. The traversal may be recursive, if the visitor returns
3972  * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
3973  * the visitor returns \c CXChildVisit_Break.
3974  *
3975  * \param parent the cursor whose child may be visited. All kinds of
3976  * cursors can be visited, including invalid cursors (which, by
3977  * definition, have no children).
3978  *
3979  * \param visitor the visitor function that will be invoked for each
3980  * child of \p parent.
3981  *
3982  * \param client_data pointer data supplied by the client, which will
3983  * be passed to the visitor each time it is invoked.
3984  *
3985  * \returns a non-zero value if the traversal was terminated
3986  * prematurely by the visitor returning \c CXChildVisit_Break.
3987  */
3989  CXCursorVisitor visitor,
3990  CXClientData client_data);
3991 #ifdef __has_feature
3992 # if __has_feature(blocks)
3993 /**
3994  * \brief Visitor invoked for each cursor found by a traversal.
3995  *
3996  * This visitor block will be invoked for each cursor found by
3997  * clang_visitChildrenWithBlock(). Its first argument is the cursor being
3998  * visited, its second argument is the parent visitor for that cursor.
3999  *
4000  * The visitor should return one of the \c CXChildVisitResult values
4001  * to direct clang_visitChildrenWithBlock().
4002  */
4003 typedef enum CXChildVisitResult
4004  (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent);
4005 
4006 /**
4007  * Visits the children of a cursor using the specified block. Behaves
4008  * identically to clang_visitChildren() in all other respects.
4009  */
4010 CINDEX_LINKAGE unsigned clang_visitChildrenWithBlock(CXCursor parent,
4011  CXCursorVisitorBlock block);
4012 # endif
4013 #endif
4014 
4015 /**
4016  * @}
4017  */
4018 
4019 /**
4020  * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
4021  *
4022  * These routines provide the ability to determine references within and
4023  * across translation units, by providing the names of the entities referenced
4024  * by cursors, follow reference cursors to the declarations they reference,
4025  * and associate declarations with their definitions.
4026  *
4027  * @{
4028  */
4029 
4030 /**
4031  * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced
4032  * by the given cursor.
4033  *
4034  * A Unified Symbol Resolution (USR) is a string that identifies a particular
4035  * entity (function, class, variable, etc.) within a program. USRs can be
4036  * compared across translation units to determine, e.g., when references in
4037  * one translation refer to an entity defined in another translation unit.
4038  */
4040 
4041 /**
4042  * \brief Construct a USR for a specified Objective-C class.
4043  */
4044 CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
4045 
4046 /**
4047  * \brief Construct a USR for a specified Objective-C category.
4048  */
4050  clang_constructUSR_ObjCCategory(const char *class_name,
4051  const char *category_name);
4052 
4053 /**
4054  * \brief Construct a USR for a specified Objective-C protocol.
4055  */
4057  clang_constructUSR_ObjCProtocol(const char *protocol_name);
4058 
4059 /**
4060  * \brief Construct a USR for a specified Objective-C instance variable and
4061  * the USR for its containing class.
4062  */
4064  CXString classUSR);
4065 
4066 /**
4067  * \brief Construct a USR for a specified Objective-C method and
4068  * the USR for its containing class.
4069  */
4071  unsigned isInstanceMethod,
4072  CXString classUSR);
4073 
4074 /**
4075  * \brief Construct a USR for a specified Objective-C property and the USR
4076  * for its containing class.
4077  */
4079  CXString classUSR);
4080 
4081 /**
4082  * \brief Retrieve a name for the entity referenced by this cursor.
4083  */
4085 
4086 /**
4087  * \brief Retrieve a range for a piece that forms the cursors spelling name.
4088  * Most of the times there is only one range for the complete spelling but for
4089  * Objective-C methods and Objective-C message expressions, there are multiple
4090  * pieces for each selector identifier.
4091  *
4092  * \param pieceIndex the index of the spelling name piece. If this is greater
4093  * than the actual number of pieces, it will return a NULL (invalid) range.
4094  *
4095  * \param options Reserved.
4096  */
4098  unsigned pieceIndex,
4099  unsigned options);
4100 
4101 /**
4102  * \brief Opaque pointer representing a policy that controls pretty printing
4103  * for \c clang_getCursorPrettyPrinted.
4104  */
4105 typedef void *CXPrintingPolicy;
4106 
4107 /**
4108  * \brief Properties for the printing policy.
4109  *
4110  * See \c clang::PrintingPolicy for more information.
4111  */
4139 
4141 };
4142 
4143 /**
4144  * \brief Get a property value for the given printing policy.
4145  */
4146 CINDEX_LINKAGE unsigned
4147 clang_PrintingPolicy_getProperty(CXPrintingPolicy Policy,
4148  enum CXPrintingPolicyProperty Property);
4149 
4150 /**
4151  * \brief Set a property value for the given printing policy.
4152  */
4153 CINDEX_LINKAGE void clang_PrintingPolicy_setProperty(CXPrintingPolicy Policy,
4154  enum CXPrintingPolicyProperty Property,
4155  unsigned Value);
4156 
4157 /**
4158  * \brief Retrieve the default policy for the cursor.
4159  *
4160  * The policy should be released after use with \c
4161  * clang_PrintingPolicy_dispose.
4162  */
4164 
4165 /**
4166  * \brief Release a printing policy.
4167  */
4168 CINDEX_LINKAGE void clang_PrintingPolicy_dispose(CXPrintingPolicy Policy);
4169 
4170 /**
4171  * \brief Pretty print declarations.
4172  *
4173  * \param Cursor The cursor representing a declaration.
4174  *
4175  * \param Policy The policy to control the entities being printed. If
4176  * NULL, a default policy is used.
4177  *
4178  * \returns The pretty printed declaration or the empty string for
4179  * other cursors.
4180  */
4182  CXPrintingPolicy Policy);
4183 
4184 /**
4185  * \brief Retrieve the display name for the entity referenced by this cursor.
4186  *
4187  * The display name contains extra information that helps identify the cursor,
4188  * such as the parameters of a function or template or the arguments of a
4189  * class template specialization.
4190  */
4192 
4193 /** \brief For a cursor that is a reference, retrieve a cursor representing the
4194  * entity that it references.
4195  *
4196  * Reference cursors refer to other entities in the AST. For example, an
4197  * Objective-C superclass reference cursor refers to an Objective-C class.
4198  * This function produces the cursor for the Objective-C class from the
4199  * cursor for the superclass reference. If the input cursor is a declaration or
4200  * definition, it returns that declaration or definition unchanged.
4201  * Otherwise, returns the NULL cursor.
4202  */
4204 
4205 /**
4206  * \brief For a cursor that is either a reference to or a declaration
4207  * of some entity, retrieve a cursor that describes the definition of
4208  * that entity.
4209  *
4210  * Some entities can be declared multiple times within a translation
4211  * unit, but only one of those declarations can also be a
4212  * definition. For example, given:
4213  *
4214  * \code
4215  * int f(int, int);
4216  * int g(int x, int y) { return f(x, y); }
4217  * int f(int a, int b) { return a + b; }
4218  * int f(int, int);
4219  * \endcode
4220  *
4221  * there are three declarations of the function "f", but only the
4222  * second one is a definition. The clang_getCursorDefinition()
4223  * function will take any cursor pointing to a declaration of "f"
4224  * (the first or fourth lines of the example) or a cursor referenced
4225  * that uses "f" (the call to "f' inside "g") and will return a
4226  * declaration cursor pointing to the definition (the second "f"
4227  * declaration).
4228  *
4229  * If given a cursor for which there is no corresponding definition,
4230  * e.g., because there is no definition of that entity within this
4231  * translation unit, returns a NULL cursor.
4232  */
4234 
4235 /**
4236  * \brief Determine whether the declaration pointed to by this cursor
4237  * is also a definition of that entity.
4238  */
4240 
4241 /**
4242  * \brief Retrieve the canonical cursor corresponding to the given cursor.
4243  *
4244  * In the C family of languages, many kinds of entities can be declared several
4245  * times within a single translation unit. For example, a structure type can
4246  * be forward-declared (possibly multiple times) and later defined:
4247  *
4248  * \code
4249  * struct X;
4250  * struct X;
4251  * struct X {
4252  * int member;
4253  * };
4254  * \endcode
4255  *
4256  * The declarations and the definition of \c X are represented by three
4257  * different cursors, all of which are declarations of the same underlying
4258  * entity. One of these cursor is considered the "canonical" cursor, which
4259  * is effectively the representative for the underlying entity. One can
4260  * determine if two cursors are declarations of the same underlying entity by
4261  * comparing their canonical cursors.
4262  *
4263  * \returns The canonical cursor for the entity referred to by the given cursor.
4264  */
4266 
4267 /**
4268  * \brief If the cursor points to a selector identifier in an Objective-C
4269  * method or message expression, this returns the selector index.
4270  *
4271  * After getting a cursor with #clang_getCursor, this can be called to
4272  * determine if the location points to a selector identifier.
4273  *
4274  * \returns The selector index if the cursor is an Objective-C method or message
4275  * expression and the cursor is pointing to a selector identifier, or -1
4276  * otherwise.
4277  */
4279 
4280 /**
4281  * \brief Given a cursor pointing to a C++ method call or an Objective-C
4282  * message, returns non-zero if the method/message is "dynamic", meaning:
4283  *
4284  * For a C++ method: the call is virtual.
4285  * For an Objective-C message: the receiver is an object instance, not 'super'
4286  * or a specific class.
4287  *
4288  * If the method/message is "static" or the cursor does not point to a
4289  * method/message, it will return zero.
4290  */
4292 
4293 /**
4294  * \brief Given a cursor pointing to an Objective-C message or property
4295  * reference, or C++ method call, returns the CXType of the receiver.
4296  */
4298 
4299 /**
4300  * \brief Property attributes for a \c CXCursor_ObjCPropertyDecl.
4301  */
4302 typedef enum {
4318 
4319 /**
4320  * \brief Given a cursor that represents a property declaration, return the
4321  * associated property attributes. The bits are formed from
4322  * \c CXObjCPropertyAttrKind.
4323  *
4324  * \param reserved Reserved for future use, pass 0.
4325  */
4327  unsigned reserved);
4328 
4329 /**
4330  * \brief 'Qualifiers' written next to the return and parameter types in
4331  * Objective-C method declarations.
4332  */
4333 typedef enum {
4342 
4343 /**
4344  * \brief Given a cursor that represents an Objective-C method or parameter
4345  * declaration, return the associated Objective-C qualifiers for the return
4346  * type or the parameter respectively. The bits are formed from
4347  * CXObjCDeclQualifierKind.
4348  */
4350 
4351 /**
4352  * \brief Given a cursor that represents an Objective-C method or property
4353  * declaration, return non-zero if the declaration was affected by "\@optional".
4354  * Returns zero if the cursor is not such a declaration or it is "\@required".
4355  */
4357 
4358 /**
4359  * \brief Returns non-zero if the given cursor is a variadic function or method.
4360  */
4362 
4363 /**
4364  * \brief Returns non-zero if the given cursor points to a symbol marked with
4365  * external_source_symbol attribute.
4366  *
4367  * \param language If non-NULL, and the attribute is present, will be set to
4368  * the 'language' string from the attribute.
4369  *
4370  * \param definedIn If non-NULL, and the attribute is present, will be set to
4371  * the 'definedIn' string from the attribute.
4372  *
4373  * \param isGenerated If non-NULL, and the attribute is present, will be set to
4374  * non-zero if the 'generated_declaration' is set in the attribute.
4375  */
4377  CXString *language, CXString *definedIn,
4378  unsigned *isGenerated);
4379 
4380 /**
4381  * \brief Given a cursor that represents a declaration, return the associated
4382  * comment's source range. The range may include multiple consecutive comments
4383  * with whitespace in between.
4384  */
4386 
4387 /**
4388  * \brief Given a cursor that represents a declaration, return the associated
4389  * comment text, including comment markers.
4390  */
4392 
4393 /**
4394  * \brief Given a cursor that represents a documentable entity (e.g.,
4395  * declaration), return the associated \\brief paragraph; otherwise return the
4396  * first paragraph.
4397  */
4399 
4400 /**
4401  * @}
4402  */
4403 
4404 /** \defgroup CINDEX_MANGLE Name Mangling API Functions
4405  *
4406  * @{
4407  */
4408 
4409 /**
4410  * \brief Retrieve the CXString representing the mangled name of the cursor.
4411  */
4413 
4414 /**
4415  * \brief Retrieve the CXStrings representing the mangled symbols of the C++
4416  * constructor or destructor at the cursor.
4417  */
4419 
4420 /**
4421  * \brief Retrieve the CXStrings representing the mangled symbols of the ObjC
4422  * class interface or implementation at the cursor.
4423  */
4425 
4426 /**
4427  * @}
4428  */
4429 
4430 /**
4431  * \defgroup CINDEX_MODULE Module introspection
4432  *
4433  * The functions in this group provide access to information about modules.
4434  *
4435  * @{
4436  */
4437 
4438 typedef void *CXModule;
4439 
4440 /**
4441  * \brief Given a CXCursor_ModuleImportDecl cursor, return the associated module.
4442  */
4444 
4445 /**
4446  * \brief Given a CXFile header file, return the module that contains it, if one
4447  * exists.
4448  */
4449 CINDEX_LINKAGE CXModule clang_getModuleForFile(CXTranslationUnit, CXFile);
4450 
4451 /**
4452  * \param Module a module object.
4453  *
4454  * \returns the module file where the provided module object came from.
4455  */
4456 CINDEX_LINKAGE CXFile clang_Module_getASTFile(CXModule Module);
4457 
4458 /**
4459  * \param Module a module object.
4460  *
4461  * \returns the parent of a sub-module or NULL if the given module is top-level,
4462  * e.g. for 'std.vector' it will return the 'std' module.
4463  */
4464 CINDEX_LINKAGE CXModule clang_Module_getParent(CXModule Module);
4465 
4466 /**
4467  * \param Module a module object.
4468  *
4469  * \returns the name of the module, e.g. for the 'std.vector' sub-module it
4470  * will return "vector".
4471  */
4473 
4474 /**
4475  * \param Module a module object.
4476  *
4477  * \returns the full name of the module, e.g. "std.vector".
4478  */
4480 
4481 /**
4482  * \param Module a module object.
4483  *
4484  * \returns non-zero if the module is a system one.
4485  */
4486 CINDEX_LINKAGE int clang_Module_isSystem(CXModule Module);
4487 
4488 /**
4489  * \param Module a module object.
4490  *
4491  * \returns the number of top level headers associated with this module.
4492  */
4493 CINDEX_LINKAGE unsigned clang_Module_getNumTopLevelHeaders(CXTranslationUnit,
4494  CXModule Module);
4495 
4496 /**
4497  * \param Module a module object.
4498  *
4499  * \param Index top level header index (zero-based).
4500  *
4501  * \returns the specified top level header associated with the module.
4502  */
4504 CXFile clang_Module_getTopLevelHeader(CXTranslationUnit,
4505  CXModule Module, unsigned Index);
4506 
4507 /**
4508  * @}
4509  */
4510 
4511 /**
4512  * \defgroup CINDEX_CPP C++ AST introspection
4513  *
4514  * The routines in this group provide access information in the ASTs specific
4515  * to C++ language features.
4516  *
4517  * @{
4518  */
4519 
4520 /**
4521  * \brief Determine if a C++ constructor is a converting constructor.
4522  */
4524 
4525 /**
4526  * \brief Determine if a C++ constructor is a copy constructor.
4527  */
4529 
4530 /**
4531  * \brief Determine if a C++ constructor is the default constructor.
4532  */
4534 
4535 /**
4536  * \brief Determine if a C++ constructor is a move constructor.
4537  */
4539 
4540 /**
4541  * \brief Determine if a C++ field is declared 'mutable'.
4542  */
4544 
4545 /**
4546  * \brief Determine if a C++ method is declared '= default'.
4547  */
4549 
4550 /**
4551  * \brief Determine if a C++ member function or member function template is
4552  * pure virtual.
4553  */
4555 
4556 /**
4557  * \brief Determine if a C++ member function or member function template is
4558  * declared 'static'.
4559  */
4561 
4562 /**
4563  * \brief Determine if a C++ member function or member function template is
4564  * explicitly declared 'virtual' or if it overrides a virtual method from
4565  * one of the base classes.
4566  */
4568 
4569 /**
4570  * \brief Determine if a C++ record is abstract, i.e. whether a class or struct
4571  * has a pure virtual member function.
4572  */
4574 
4575 /**
4576  * \brief Determine if an enum declaration refers to a scoped enum.
4577  */
4579 
4580 /**
4581  * \brief Determine if a C++ member function or member function template is
4582  * declared 'const'.
4583  */
4585 
4586 /**
4587  * \brief Given a cursor that represents a template, determine
4588  * the cursor kind of the specializations would be generated by instantiating
4589  * the template.
4590  *
4591  * This routine can be used to determine what flavor of function template,
4592  * class template, or class template partial specialization is stored in the
4593  * cursor. For example, it can describe whether a class template cursor is
4594  * declared with "struct", "class" or "union".
4595  *
4596  * \param C The cursor to query. This cursor should represent a template
4597  * declaration.
4598  *
4599  * \returns The cursor kind of the specializations that would be generated
4600  * by instantiating the template \p C. If \p C is not a template, returns
4601  * \c CXCursor_NoDeclFound.
4602  */
4604 
4605 /**
4606  * \brief Given a cursor that may represent a specialization or instantiation
4607  * of a template, retrieve the cursor that represents the template that it
4608  * specializes or from which it was instantiated.
4609  *
4610  * This routine determines the template involved both for explicit
4611  * specializations of templates and for implicit instantiations of the template,
4612  * both of which are referred to as "specializations". For a class template
4613  * specialization (e.g., \c std::vector<bool>), this routine will return
4614  * either the primary template (\c std::vector) or, if the specialization was
4615  * instantiated from a class template partial specialization, the class template
4616  * partial specialization. For a class template partial specialization and a
4617  * function template specialization (including instantiations), this
4618  * this routine will return the specialized template.
4619  *
4620  * For members of a class template (e.g., member functions, member classes, or
4621  * static data members), returns the specialized or instantiated member.
4622  * Although not strictly "templates" in the C++ language, members of class
4623  * templates have the same notions of specializations and instantiations that
4624  * templates do, so this routine treats them similarly.
4625  *
4626  * \param C A cursor that may be a specialization of a template or a member
4627  * of a template.
4628  *
4629  * \returns If the given cursor is a specialization or instantiation of a
4630  * template or a member thereof, the template or member that it specializes or
4631  * from which it was instantiated. Otherwise, returns a NULL cursor.
4632  */
4634 
4635 /**
4636  * \brief Given a cursor that references something else, return the source range
4637  * covering that reference.
4638  *
4639  * \param C A cursor pointing to a member reference, a declaration reference, or
4640  * an operator call.
4641  * \param NameFlags A bitset with three independent flags:
4642  * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and
4643  * CXNameRange_WantSinglePiece.
4644  * \param PieceIndex For contiguous names or when passing the flag
4645  * CXNameRange_WantSinglePiece, only one piece with index 0 is
4646  * available. When the CXNameRange_WantSinglePiece flag is not passed for a
4647  * non-contiguous names, this index can be used to retrieve the individual
4648  * pieces of the name. See also CXNameRange_WantSinglePiece.
4649  *
4650  * \returns The piece of the name pointed to by the given cursor. If there is no
4651  * name, or if the PieceIndex is out-of-range, a null-cursor will be returned.
4652  */
4654  unsigned NameFlags,
4655  unsigned PieceIndex);
4656 
4658  /**
4659  * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the
4660  * range.
4661  */
4663 
4664  /**
4665  * \brief Include the explicit template arguments, e.g. <int> in x.f<int>,
4666  * in the range.
4667  */
4669 
4670  /**
4671  * \brief If the name is non-contiguous, return the full spanning range.
4672  *
4673  * Non-contiguous names occur in Objective-C when a selector with two or more
4674  * parameters is used, or in C++ when using an operator:
4675  * \code
4676  * [object doSomething:here withValue:there]; // Objective-C
4677  * return some_vector[1]; // C++
4678  * \endcode
4679  */
4681 };
4682 
4683 /**
4684  * @}
4685  */
4686 
4687 /**
4688  * \defgroup CINDEX_LEX Token extraction and manipulation
4689  *
4690  * The routines in this group provide access to the tokens within a
4691  * translation unit, along with a semantic mapping of those tokens to
4692  * their corresponding cursors.
4693  *
4694  * @{
4695  */
4696 
4697 /**
4698  * \brief Describes a kind of token.
4699  */
4700 typedef enum CXTokenKind {
4701  /**
4702  * \brief A token that contains some kind of punctuation.
4703  */
4705 
4706  /**
4707  * \brief A language keyword.
4708  */
4710 
4711  /**
4712  * \brief An identifier (that is not a keyword).
4713  */
4715 
4716  /**
4717  * \brief A numeric, string, or character literal.
4718  */
4720 
4721  /**
4722  * \brief A comment.
4723  */
4725 } CXTokenKind;
4726 
4727 /**
4728  * \brief Describes a single preprocessing token.
4729  */
4730 typedef struct {
4731  unsigned int_data[4];
4732  void *ptr_data;
4733 } CXToken;
4734 
4735 /**
4736  * \brief Determine the kind of the given token.
4737  */
4739 
4740 /**
4741  * \brief Determine the spelling of the given token.
4742  *
4743  * The spelling of a token is the textual representation of that token, e.g.,
4744  * the text of an identifier or keyword.
4745  */
4747 
4748 /**
4749  * \brief Retrieve the source location of the given token.
4750  */
4752  CXToken);
4753 
4754 /**
4755  * \brief Retrieve a source range that covers the given token.
4756  */
4758 
4759 /**
4760  * \brief Tokenize the source code described by the given range into raw
4761  * lexical tokens.
4762  *
4763  * \param TU the translation unit whose text is being tokenized.
4764  *
4765  * \param Range the source range in which text should be tokenized. All of the
4766  * tokens produced by tokenization will fall within this source range,
4767  *
4768  * \param Tokens this pointer will be set to point to the array of tokens
4769  * that occur within the given source range. The returned pointer must be
4770  * freed with clang_disposeTokens() before the translation unit is destroyed.
4771  *
4772  * \param NumTokens will be set to the number of tokens in the \c *Tokens
4773  * array.
4774  *
4775  */
4776 CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
4777  CXToken **Tokens, unsigned *NumTokens);
4778 
4779 /**
4780  * \brief Annotate the given set of tokens by providing cursors for each token
4781  * that can be mapped to a specific entity within the abstract syntax tree.
4782  *
4783  * This token-annotation routine is equivalent to invoking
4784  * clang_getCursor() for the source locations of each of the
4785  * tokens. The cursors provided are filtered, so that only those
4786  * cursors that have a direct correspondence to the token are
4787  * accepted. For example, given a function call \c f(x),
4788  * clang_getCursor() would provide the following cursors:
4789  *
4790  * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
4791  * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
4792  * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
4793  *
4794  * Only the first and last of these cursors will occur within the
4795  * annotate, since the tokens "f" and "x' directly refer to a function
4796  * and a variable, respectively, but the parentheses are just a small
4797  * part of the full syntax of the function call expression, which is
4798  * not provided as an annotation.
4799  *
4800  * \param TU the translation unit that owns the given tokens.
4801  *
4802  * \param Tokens the set of tokens to annotate.
4803  *
4804  * \param NumTokens the number of tokens in \p Tokens.
4805  *
4806  * \param Cursors an array of \p NumTokens cursors, whose contents will be
4807  * replaced with the cursors corresponding to each token.
4808  */
4809 CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU,
4810  CXToken *Tokens, unsigned NumTokens,
4811  CXCursor *Cursors);
4812 
4813 /**
4814  * \brief Free the given set of tokens.
4815  */
4816 CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU,
4817  CXToken *Tokens, unsigned NumTokens);
4818 
4819 /**
4820  * @}
4821  */
4822 
4823 /**
4824  * \defgroup CINDEX_DEBUG Debugging facilities
4825  *
4826  * These routines are used for testing and debugging, only, and should not
4827  * be relied upon.
4828  *
4829  * @{
4830  */
4831 
4832 /* for debug/testing */
4835  const char **startBuf,
4836  const char **endBuf,
4837  unsigned *startLine,
4838  unsigned *startColumn,
4839  unsigned *endLine,
4840  unsigned *endColumn);
4842 CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data,
4843  unsigned stack_size);
4844 
4845 /**
4846  * @}
4847  */
4848 
4849 /**
4850  * \defgroup CINDEX_CODE_COMPLET Code completion
4851  *
4852  * Code completion involves taking an (incomplete) source file, along with
4853  * knowledge of where the user is actively editing that file, and suggesting
4854  * syntactically- and semantically-valid constructs that the user might want to
4855  * use at that particular point in the source code. These data structures and
4856  * routines provide support for code completion.
4857  *
4858  * @{
4859  */
4860 
4861 /**
4862  * \brief A semantic string that describes a code-completion result.
4863  *
4864  * A semantic string that describes the formatting of a code-completion
4865  * result as a single "template" of text that should be inserted into the
4866  * source buffer when a particular code-completion result is selected.
4867  * Each semantic string is made up of some number of "chunks", each of which
4868  * contains some text along with a description of what that text means, e.g.,
4869  * the name of the entity being referenced, whether the text chunk is part of
4870  * the template, or whether it is a "placeholder" that the user should replace
4871  * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
4872  * description of the different kinds of chunks.
4873  */
4874 typedef void *CXCompletionString;
4875 
4876 /**
4877  * \brief A single result of code completion.
4878  */
4879 typedef struct {
4880  /**
4881  * \brief The kind of entity that this completion refers to.
4882  *
4883  * The cursor kind will be a macro, keyword, or a declaration (one of the
4884  * *Decl cursor kinds), describing the entity that the completion is
4885  * referring to.
4886  *
4887  * \todo In the future, we would like to provide a full cursor, to allow
4888  * the client to extract additional information from declaration.
4889  */
4890  enum CXCursorKind CursorKind;
4891 
4892  /**
4893  * \brief The code-completion string that describes how to insert this
4894  * code-completion result into the editing buffer.
4895  */
4896  CXCompletionString CompletionString;
4898 
4899 /**
4900  * \brief Describes a single piece of text within a code-completion string.
4901  *
4902  * Each "chunk" within a code-completion string (\c CXCompletionString) is
4903  * either a piece of text with a specific "kind" that describes how that text
4904  * should be interpreted by the client or is another completion string.
4905  */
4907  /**
4908  * \brief A code-completion string that describes "optional" text that
4909  * could be a part of the template (but is not required).
4910  *
4911  * The Optional chunk is the only kind of chunk that has a code-completion
4912  * string for its representation, which is accessible via
4913  * \c clang_getCompletionChunkCompletionString(). The code-completion string
4914  * describes an additional part of the template that is completely optional.
4915  * For example, optional chunks can be used to describe the placeholders for
4916  * arguments that match up with defaulted function parameters, e.g. given:
4917  *
4918  * \code
4919  * void f(int x, float y = 3.14, double z = 2.71828);
4920  * \endcode
4921  *
4922  * The code-completion string for this function would contain:
4923  * - a TypedText chunk for "f".
4924  * - a LeftParen chunk for "(".
4925  * - a Placeholder chunk for "int x"
4926  * - an Optional chunk containing the remaining defaulted arguments, e.g.,
4927  * - a Comma chunk for ","
4928  * - a Placeholder chunk for "float y"
4929  * - an Optional chunk containing the last defaulted argument:
4930  * - a Comma chunk for ","
4931  * - a Placeholder chunk for "double z"
4932  * - a RightParen chunk for ")"
4933  *
4934  * There are many ways to handle Optional chunks. Two simple approaches are:
4935  * - Completely ignore optional chunks, in which case the template for the
4936  * function "f" would only include the first parameter ("int x").
4937  * - Fully expand all optional chunks, in which case the template for the
4938  * function "f" would have all of the parameters.
4939  */
4941  /**
4942  * \brief Text that a user would be expected to type to get this
4943  * code-completion result.
4944  *
4945  * There will be exactly one "typed text" chunk in a semantic string, which
4946  * will typically provide the spelling of a keyword or the name of a
4947  * declaration that could be used at the current code point. Clients are
4948  * expected to filter the code-completion results based on the text in this
4949  * chunk.
4950  */
4952  /**
4953  * \brief Text that should be inserted as part of a code-completion result.
4954  *
4955  * A "text" chunk represents text that is part of the template to be
4956  * inserted into user code should this particular code-completion result
4957  * be selected.
4958  */
4960  /**
4961  * \brief Placeholder text that should be replaced by the user.
4962  *
4963  * A "placeholder" chunk marks a place where the user should insert text
4964  * into the code-completion template. For example, placeholders might mark
4965  * the function parameters for a function declaration, to indicate that the
4966  * user should provide arguments for each of those parameters. The actual
4967  * text in a placeholder is a suggestion for the text to display before
4968  * the user replaces the placeholder with real code.
4969  */
4971  /**
4972  * \brief Informative text that should be displayed but never inserted as
4973  * part of the template.
4974  *
4975  * An "informative" chunk contains annotations that can be displayed to
4976  * help the user decide whether a particular code-completion result is the
4977  * right option, but which is not part of the actual template to be inserted
4978  * by code completion.
4979  */
4981  /**
4982  * \brief Text that describes the current parameter when code-completion is
4983  * referring to function call, message send, or template specialization.
4984  *
4985  * A "current parameter" chunk occurs when code-completion is providing
4986  * information about a parameter corresponding to the argument at the
4987  * code-completion point. For example, given a function
4988  *
4989  * \code
4990  * int add(int x, int y);
4991  * \endcode
4992  *
4993  * and the source code \c add(, where the code-completion point is after the
4994  * "(", the code-completion string will contain a "current parameter" chunk
4995  * for "int x", indicating that the current argument will initialize that
4996  * parameter. After typing further, to \c add(17, (where the code-completion
4997  * point is after the ","), the code-completion string will contain a
4998  * "current parameter" chunk to "int y".
4999  */
5001  /**
5002  * \brief A left parenthesis ('('), used to initiate a function call or
5003  * signal the beginning of a function parameter list.
5004  */
5006  /**
5007  * \brief A right parenthesis (')'), used to finish a function call or
5008  * signal the end of a function parameter list.
5009  */
5011  /**
5012  * \brief A left bracket ('[').
5013  */
5015  /**
5016  * \brief A right bracket (']').
5017  */
5019  /**
5020  * \brief A left brace ('{').
5021  */
5023  /**
5024  * \brief A right brace ('}').
5025  */
5027  /**
5028  * \brief A left angle bracket ('<').
5029  */
5031  /**
5032  * \brief A right angle bracket ('>').
5033  */
5035  /**
5036  * \brief A comma separator (',').
5037  */
5039  /**
5040  * \brief Text that specifies the result type of a given result.
5041  *
5042  * This special kind of informative chunk is not meant to be inserted into
5043  * the text buffer. Rather, it is meant to illustrate the type that an
5044  * expression using the given completion string would have.
5045  */
5047  /**
5048  * \brief A colon (':').
5049  */
5051  /**
5052  * \brief A semicolon (';').
5053  */
5055  /**
5056  * \brief An '=' sign.
5057  */
5059  /**
5060  * Horizontal space (' ').
5061  */
5063  /**
5064  * Vertical space ('\\n'), after which it is generally a good idea to
5065  * perform indentation.
5066  */
5068 };
5069 
5070 /**
5071  * \brief Determine the kind of a particular chunk within a completion string.
5072  *
5073  * \param completion_string the completion string to query.
5074  *
5075  * \param chunk_number the 0-based index of the chunk in the completion string.
5076  *
5077  * \returns the kind of the chunk at the index \c chunk_number.
5078  */
5080 clang_getCompletionChunkKind(CXCompletionString completion_string,
5081  unsigned chunk_number);
5082 
5083 /**
5084  * \brief Retrieve the text associated with a particular chunk within a
5085  * completion string.
5086  *
5087  * \param completion_string the completion string to query.
5088  *
5089  * \param chunk_number the 0-based index of the chunk in the completion string.
5090  *
5091  * \returns the text associated with the chunk at index \c chunk_number.
5092  */
5094 clang_getCompletionChunkText(CXCompletionString completion_string,
5095  unsigned chunk_number);
5096 
5097 /**
5098  * \brief Retrieve the completion string associated with a particular chunk
5099  * within a completion string.
5100  *
5101  * \param completion_string the completion string to query.
5102  *
5103  * \param chunk_number the 0-based index of the chunk in the completion string.
5104  *
5105  * \returns the completion string associated with the chunk at index
5106  * \c chunk_number.
5107  */
5108 CINDEX_LINKAGE CXCompletionString
5109 clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
5110  unsigned chunk_number);
5111 
5112 /**
5113  * \brief Retrieve the number of chunks in the given code-completion string.
5114  */
5115 CINDEX_LINKAGE unsigned
5116 clang_getNumCompletionChunks(CXCompletionString completion_string);
5117 
5118 /**
5119  * \brief Determine the priority of this code completion.
5120  *
5121  * The priority of a code completion indicates how likely it is that this
5122  * particular completion is the completion that the user will select. The
5123  * priority is selected by various internal heuristics.
5124  *
5125  * \param completion_string The completion string to query.
5126  *
5127  * \returns The priority of this completion string. Smaller values indicate
5128  * higher-priority (more likely) completions.
5129  */
5130 CINDEX_LINKAGE unsigned
5131 clang_getCompletionPriority(CXCompletionString completion_string);
5132 
5133 /**
5134  * \brief Determine the availability of the entity that this code-completion
5135  * string refers to.
5136  *
5137  * \param completion_string The completion string to query.
5138  *
5139  * \returns The availability of the completion string.
5140  */
5142 clang_getCompletionAvailability(CXCompletionString completion_string);
5143 
5144 /**
5145  * \brief Retrieve the number of annotations associated with the given
5146  * completion string.
5147  *
5148  * \param completion_string the completion string to query.
5149  *
5150  * \returns the number of annotations associated with the given completion
5151  * string.
5152  */
5153 CINDEX_LINKAGE unsigned
5154 clang_getCompletionNumAnnotations(CXCompletionString completion_string);
5155 
5156 /**
5157  * \brief Retrieve the annotation associated with the given completion string.
5158  *
5159  * \param completion_string the completion string to query.
5160  *
5161  * \param annotation_number the 0-based index of the annotation of the
5162  * completion string.
5163  *
5164  * \returns annotation string associated with the completion at index
5165  * \c annotation_number, or a NULL string if that annotation is not available.
5166  */
5168 clang_getCompletionAnnotation(CXCompletionString completion_string,
5169  unsigned annotation_number);
5170 
5171 /**
5172  * \brief Retrieve the parent context of the given completion string.
5173  *
5174  * The parent context of a completion string is the semantic parent of
5175  * the declaration (if any) that the code completion represents. For example,
5176  * a code completion for an Objective-C method would have the method's class
5177  * or protocol as its context.
5178  *
5179  * \param completion_string The code completion string whose parent is
5180  * being queried.
5181  *
5182  * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL.
5183  *
5184  * \returns The name of the completion parent, e.g., "NSObject" if
5185  * the completion string represents a method in the NSObject class.
5186  */
5188 clang_getCompletionParent(CXCompletionString completion_string,
5189  enum CXCursorKind *kind);
5190 
5191 /**
5192  * \brief Retrieve the brief documentation comment attached to the declaration
5193  * that corresponds to the given completion string.
5194  */
5196 clang_getCompletionBriefComment(CXCompletionString completion_string);
5197 
5198 /**
5199  * \brief Retrieve a completion string for an arbitrary declaration or macro
5200  * definition cursor.
5201  *
5202  * \param cursor The cursor to query.
5203  *
5204  * \returns A non-context-sensitive completion string for declaration and macro
5205  * definition cursors, or NULL for other kinds of cursors.
5206  */
5207 CINDEX_LINKAGE CXCompletionString
5209 
5210 /**
5211  * \brief Contains the results of code-completion.
5212  *
5213  * This data structure contains the results of code completion, as
5214  * produced by \c clang_codeCompleteAt(). Its contents must be freed by
5215  * \c clang_disposeCodeCompleteResults.
5216  */
5217 typedef struct {
5218  /**
5219  * \brief The code-completion results.
5220  */
5222 
5223  /**
5224  * \brief The number of code-completion results stored in the
5225  * \c Results array.
5226  */
5227  unsigned NumResults;
5229 
5230 /**
5231  * \brief Flags that can be passed to \c clang_codeCompleteAt() to
5232  * modify its behavior.
5233  *
5234  * The enumerators in this enumeration can be bitwise-OR'd together to
5235  * provide multiple options to \c clang_codeCompleteAt().
5236  */
5238  /**
5239  * \brief Whether to include macros within the set of code
5240  * completions returned.
5241  */
5243 
5244  /**
5245  * \brief Whether to include code patterns for language constructs
5246  * within the set of code completions, e.g., for loops.
5247  */
5249 
5250  /**
5251  * \brief Whether to include brief documentation within the set of code
5252  * completions returned.
5253  */
5255 
5256  /**
5257  * Whether to speed up completion by omitting top- or namespace-level entities
5258  * defined in the preamble. There's no guarantee any particular entity is
5259  * omitted. This may be useful if the headers are indexed externally.
5260  */
5262 };
5263 
5264 /**
5265  * \brief Bits that represent the context under which completion is occurring.
5266  *
5267  * The enumerators in this enumeration may be bitwise-OR'd together if multiple
5268  * contexts are occurring simultaneously.
5269  */
5271  /**
5272  * \brief The context for completions is unexposed, as only Clang results
5273  * should be included. (This is equivalent to having no context bits set.)
5274  */
5276 
5277  /**
5278  * \brief Completions for any possible type should be included in the results.
5279  */
5281 
5282  /**
5283  * \brief Completions for any possible value (variables, function calls, etc.)
5284  * should be included in the results.
5285  */
5287  /**
5288  * \brief Completions for values that resolve to an Objective-C object should
5289  * be included in the results.
5290  */
5292  /**
5293  * \brief Completions for values that resolve to an Objective-C selector
5294  * should be included in the results.
5295  */
5297  /**
5298  * \brief Completions for values that resolve to a C++ class type should be
5299  * included in the results.
5300  */
5302 
5303  /**
5304  * \brief Completions for fields of the member being accessed using the dot
5305  * operator should be included in the results.
5306  */
5308  /**
5309  * \brief Completions for fields of the member being accessed using the arrow
5310  * operator should be included in the results.
5311  */
5313  /**
5314  * \brief Completions for properties of the Objective-C object being accessed
5315  * using the dot operator should be included in the results.
5316  */
5318 
5319  /**
5320  * \brief Completions for enum tags should be included in the results.
5321  */
5323  /**
5324  * \brief Completions for union tags should be included in the results.
5325  */
5327  /**
5328  * \brief Completions for struct tags should be included in the results.
5329  */
5331 
5332  /**
5333  * \brief Completions for C++ class names should be included in the results.
5334  */
5336  /**
5337  * \brief Completions for C++ namespaces and namespace aliases should be
5338  * included in the results.
5339  */
5341  /**
5342  * \brief Completions for C++ nested name specifiers should be included in
5343  * the results.
5344  */
5346 
5347  /**
5348  * \brief Completions for Objective-C interfaces (classes) should be included
5349  * in the results.
5350  */
5352  /**
5353  * \brief Completions for Objective-C protocols should be included in
5354  * the results.
5355  */
5357  /**
5358  * \brief Completions for Objective-C categories should be included in
5359  * the results.
5360  */
5362  /**
5363  * \brief Completions for Objective-C instance messages should be included
5364  * in the results.
5365  */
5367  /**
5368  * \brief Completions for Objective-C class messages should be included in
5369  * the results.
5370  */
5372  /**
5373  * \brief Completions for Objective-C selector names should be included in
5374  * the results.
5375  */
5377 
5378  /**
5379  * \brief Completions for preprocessor macro names should be included in
5380  * the results.
5381  */
5383 
5384  /**
5385  * \brief Natural language completions should be included in the results.
5386  */
5388 
5389  /**
5390  * \brief The current context is unknown, so set all contexts.
5391  */
5393 };
5394 
5395 /**
5396  * \brief Returns a default set of code-completion options that can be
5397  * passed to\c clang_codeCompleteAt().
5398  */
5400 
5401 /**
5402  * \brief Perform code completion at a given location in a translation unit.
5403  *
5404  * This function performs code completion at a particular file, line, and
5405  * column within source code, providing results that suggest potential
5406  * code snippets based on the context of the completion. The basic model
5407  * for code completion is that Clang will parse a complete source file,
5408  * performing syntax checking up to the location where code-completion has
5409  * been requested. At that point, a special code-completion token is passed
5410  * to the parser, which recognizes this token and determines, based on the
5411  * current location in the C/Objective-C/C++ grammar and the state of
5412  * semantic analysis, what completions to provide. These completions are
5413  * returned via a new \c CXCodeCompleteResults structure.
5414  *
5415  * Code completion itself is meant to be triggered by the client when the
5416  * user types punctuation characters or whitespace, at which point the
5417  * code-completion location will coincide with the cursor. For example, if \c p
5418  * is a pointer, code-completion might be triggered after the "-" and then
5419  * after the ">" in \c p->. When the code-completion location is after the ">",
5420  * the completion results will provide, e.g., the members of the struct that
5421  * "p" points to. The client is responsible for placing the cursor at the
5422  * beginning of the token currently being typed, then filtering the results
5423  * based on the contents of the token. For example, when code-completing for
5424  * the expression \c p->get, the client should provide the location just after
5425  * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
5426  * client can filter the results based on the current token text ("get"), only
5427  * showing those results that start with "get". The intent of this interface
5428  * is to separate the relatively high-latency acquisition of code-completion
5429  * results from the filtering of results on a per-character basis, which must
5430  * have a lower latency.
5431  *
5432  * \param TU The translation unit in which code-completion should
5433  * occur. The source files for this translation unit need not be
5434  * completely up-to-date (and the contents of those source files may
5435  * be overridden via \p unsaved_files). Cursors referring into the
5436  * translation unit may be invalidated by this invocation.
5437  *
5438  * \param complete_filename The name of the source file where code
5439  * completion should be performed. This filename may be any file
5440  * included in the translation unit.
5441  *
5442  * \param complete_line The line at which code-completion should occur.
5443  *
5444  * \param complete_column The column at which code-completion should occur.
5445  * Note that the column should point just after the syntactic construct that
5446  * initiated code completion, and not in the middle of a lexical token.
5447  *
5448  * \param unsaved_files the Files that have not yet been saved to disk
5449  * but may be required for parsing or code completion, including the
5450  * contents of those files. The contents and name of these files (as
5451  * specified by CXUnsavedFile) are copied when necessary, so the
5452  * client only needs to guarantee their validity until the call to
5453  * this function returns.
5454  *
5455  * \param num_unsaved_files The number of unsaved file entries in \p
5456  * unsaved_files.
5457  *
5458  * \param options Extra options that control the behavior of code
5459  * completion, expressed as a bitwise OR of the enumerators of the
5460  * CXCodeComplete_Flags enumeration. The
5461  * \c clang_defaultCodeCompleteOptions() function returns a default set
5462  * of code-completion options.
5463  *
5464  * \returns If successful, a new \c CXCodeCompleteResults structure
5465  * containing code-completion results, which should eventually be
5466  * freed with \c clang_disposeCodeCompleteResults(). If code
5467  * completion fails, returns NULL.
5468  */
5470 CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU,
5471  const char *complete_filename,
5472  unsigned complete_line,
5473  unsigned complete_column,
5474  struct CXUnsavedFile *unsaved_files,
5475  unsigned num_unsaved_files,
5476  unsigned options);
5477 
5478 /**
5479  * \brief Sort the code-completion results in case-insensitive alphabetical
5480  * order.
5481  *
5482  * \param Results The set of results to sort.
5483  * \param NumResults The number of results in \p Results.
5484  */
5487  unsigned NumResults);
5488 
5489 /**
5490  * \brief Free the given set of code-completion results.
5491  */
5494 
5495 /**
5496  * \brief Determine the number of diagnostics produced prior to the
5497  * location where code completion was performed.
5498  */
5501 
5502 /**
5503  * \brief Retrieve a diagnostic associated with the given code completion.
5504  *
5505  * \param Results the code completion results to query.
5506  * \param Index the zero-based diagnostic number to retrieve.
5507  *
5508  * \returns the requested diagnostic. This diagnostic must be freed
5509  * via a call to \c clang_disposeDiagnostic().
5510  */
5513  unsigned Index);
5514 
5515 /**
5516  * \brief Determines what completions are appropriate for the context
5517  * the given code completion.
5518  *
5519  * \param Results the code completion results to query
5520  *
5521  * \returns the kinds of completions that are appropriate for use
5522  * along with the given code completion results.
5523  */
5525 unsigned long long clang_codeCompleteGetContexts(
5526  CXCodeCompleteResults *Results);
5527 
5528 /**
5529  * \brief Returns the cursor kind for the container for the current code
5530  * completion context. The container is only guaranteed to be set for
5531  * contexts where a container exists (i.e. member accesses or Objective-C
5532  * message sends); if there is not a container, this function will return
5533  * CXCursor_InvalidCode.
5534  *
5535  * \param Results the code completion results to query
5536  *
5537  * \param IsIncomplete on return, this value will be false if Clang has complete
5538  * information about the container. If Clang does not have complete
5539  * information, this value will be true.
5540  *
5541  * \returns the container kind, or CXCursor_InvalidCode if there is not a
5542  * container
5543  */
5546  CXCodeCompleteResults *Results,
5547  unsigned *IsIncomplete);
5548 
5549 /**
5550  * \brief Returns the USR for the container for the current code completion
5551  * context. If there is not a container for the current context, this
5552  * function will return the empty string.
5553  *
5554  * \param Results the code completion results to query
5555  *
5556  * \returns the USR for the container
5557  */
5560 
5561 /**
5562  * \brief Returns the currently-entered selector for an Objective-C message
5563  * send, formatted like "initWithFoo:bar:". Only guaranteed to return a
5564  * non-empty string for CXCompletionContext_ObjCInstanceMessage and
5565  * CXCompletionContext_ObjCClassMessage.
5566  *
5567  * \param Results the code completion results to query
5568  *
5569  * \returns the selector (or partial selector) that has been entered thus far
5570  * for an Objective-C message send.
5571  */
5574 
5575 /**
5576  * @}
5577  */
5578 
5579 /**
5580  * \defgroup CINDEX_MISC Miscellaneous utility functions
5581  *
5582  * @{
5583  */
5584 
5585 /**
5586  * \brief Return a version string, suitable for showing to a user, but not
5587  * intended to be parsed (the format is not guaranteed to be stable).
5588  */
5590 
5591 /**
5592  * \brief Enable/disable crash recovery.
5593  *
5594  * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero
5595  * value enables crash recovery, while 0 disables it.
5596  */
5598 
5599  /**
5600  * \brief Visitor invoked for each file in a translation unit
5601  * (used with clang_getInclusions()).
5602  *
5603  * This visitor function will be invoked by clang_getInclusions() for each
5604  * file included (either at the top-level or by \#include directives) within
5605  * a translation unit. The first argument is the file being included, and
5606  * the second and third arguments provide the inclusion stack. The
5607  * array is sorted in order of immediate inclusion. For example,
5608  * the first element refers to the location that included 'included_file'.
5609  */
5610 typedef void (*CXInclusionVisitor)(CXFile included_file,
5611  CXSourceLocation* inclusion_stack,
5612  unsigned include_len,
5613  CXClientData client_data);
5614 
5615 /**
5616  * \brief Visit the set of preprocessor inclusions in a translation unit.
5617  * The visitor function is called with the provided data for every included
5618  * file. This does not include headers included by the PCH file (unless one
5619  * is inspecting the inclusions in the PCH file itself).
5620  */
5621 CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
5622  CXInclusionVisitor visitor,
5623  CXClientData client_data);
5624 
5625 typedef enum {
5632 
5634 
5635 } CXEvalResultKind ;
5636 
5637 /**
5638  * \brief Evaluation result of a cursor
5639  */
5640 typedef void * CXEvalResult;
5641 
5642 /**
5643  * \brief If cursor is a statement declaration tries to evaluate the
5644  * statement and if its variable, tries to evaluate its initializer,
5645  * into its corresponding type.
5646  */
5648 
5649 /**
5650  * \brief Returns the kind of the evaluated result.
5651  */
5653 
5654 /**
5655  * \brief Returns the evaluation result as integer if the
5656  * kind is Int.
5657  */
5658 CINDEX_LINKAGE int clang_EvalResult_getAsInt(CXEvalResult E);
5659 
5660 /**
5661  * \brief Returns the evaluation result as a long long integer if the
5662  * kind is Int. This prevents overflows that may happen if the result is
5663  * returned with clang_EvalResult_getAsInt.
5664  */
5665 CINDEX_LINKAGE long long clang_EvalResult_getAsLongLong(CXEvalResult E);
5666 
5667 /**
5668  * \brief Returns a non-zero value if the kind is Int and the evaluation
5669  * result resulted in an unsigned integer.
5670  */
5671 CINDEX_LINKAGE unsigned clang_EvalResult_isUnsignedInt(CXEvalResult E);
5672 
5673 /**
5674  * \brief Returns the evaluation result as an unsigned integer if
5675  * the kind is Int and clang_EvalResult_isUnsignedInt is non-zero.
5676  */
5677 CINDEX_LINKAGE unsigned long long clang_EvalResult_getAsUnsigned(CXEvalResult E);
5678 
5679 /**
5680  * \brief Returns the evaluation result as double if the
5681  * kind is double.
5682  */