clang  5.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 43
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 Provides a shared context for creating translation units.
177  *
178  * It provides two options:
179  *
180  * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
181  * declarations (when loading any new translation units). A "local" declaration
182  * is one that belongs in the translation unit itself and not in a precompiled
183  * header that was used by the translation unit. If zero, all declarations
184  * will be enumerated.
185  *
186  * Here is an example:
187  *
188  * \code
189  * // excludeDeclsFromPCH = 1, displayDiagnostics=1
190  * Idx = clang_createIndex(1, 1);
191  *
192  * // IndexTest.pch was produced with the following command:
193  * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
194  * TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
195  *
196  * // This will load all the symbols from 'IndexTest.pch'
197  * clang_visitChildren(clang_getTranslationUnitCursor(TU),
198  * TranslationUnitVisitor, 0);
199  * clang_disposeTranslationUnit(TU);
200  *
201  * // This will load all the symbols from 'IndexTest.c', excluding symbols
202  * // from 'IndexTest.pch'.
203  * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
204  * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
205  * 0, 0);
206  * clang_visitChildren(clang_getTranslationUnitCursor(TU),
207  * TranslationUnitVisitor, 0);
208  * clang_disposeTranslationUnit(TU);
209  * \endcode
210  *
211  * This process of creating the 'pch', loading it separately, and using it (via
212  * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
213  * (which gives the indexer the same performance benefit as the compiler).
214  */
215 CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
216  int displayDiagnostics);
217 
218 /**
219  * \brief Destroy the given index.
220  *
221  * The index must not be destroyed until all of the translation units created
222  * within that index have been destroyed.
223  */
224 CINDEX_LINKAGE void clang_disposeIndex(CXIndex index);
225 
226 typedef enum {
227  /**
228  * \brief Used to indicate that no special CXIndex options are needed.
229  */
231 
232  /**
233  * \brief Used to indicate that threads that libclang creates for indexing
234  * purposes should use background priority.
235  *
236  * Affects #clang_indexSourceFile, #clang_indexTranslationUnit,
237  * #clang_parseTranslationUnit, #clang_saveTranslationUnit.
238  */
240 
241  /**
242  * \brief Used to indicate that threads that libclang creates for editing
243  * purposes should use background priority.
244  *
245  * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt,
246  * #clang_annotateTokens
247  */
249 
250  /**
251  * \brief Used to indicate that all threads that libclang creates should use
252  * background priority.
253  */
257 
259 
260 /**
261  * \brief Sets general options associated with a CXIndex.
262  *
263  * For example:
264  * \code
265  * CXIndex idx = ...;
266  * clang_CXIndex_setGlobalOptions(idx,
267  * clang_CXIndex_getGlobalOptions(idx) |
268  * CXGlobalOpt_ThreadBackgroundPriorityForIndexing);
269  * \endcode
270  *
271  * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags.
272  */
273 CINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options);
274 
275 /**
276  * \brief Gets the general options associated with a CXIndex.
277  *
278  * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that
279  * are associated with the given CXIndex object.
280  */
282 
283 /**
284  * \defgroup CINDEX_FILES File manipulation routines
285  *
286  * @{
287  */
288 
289 /**
290  * \brief A particular source file that is part of a translation unit.
291  */
292 typedef void *CXFile;
293 
294 /**
295  * \brief Retrieve the complete file and path name of the given file.
296  */
298 
299 /**
300  * \brief Retrieve the last modification time of the given file.
301  */
302 CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile);
303 
304 /**
305  * \brief Uniquely identifies a CXFile, that refers to the same underlying file,
306  * across an indexing session.
307  */
308 typedef struct {
309  unsigned long long data[3];
311 
312 /**
313  * \brief Retrieve the unique ID for the given \c file.
314  *
315  * \param file the file to get the ID for.
316  * \param outID stores the returned CXFileUniqueID.
317  * \returns If there was a failure getting the unique ID, returns non-zero,
318  * otherwise returns 0.
319 */
320 CINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID);
321 
322 /**
323  * \brief Determine whether the given header is guarded against
324  * multiple inclusions, either with the conventional
325  * \#ifndef/\#define/\#endif macro guards or with \#pragma once.
326  */
327 CINDEX_LINKAGE unsigned
328 clang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file);
329 
330 /**
331  * \brief Retrieve a file handle within the given translation unit.
332  *
333  * \param tu the translation unit
334  *
335  * \param file_name the name of the file.
336  *
337  * \returns the file handle for the named file in the translation unit \p tu,
338  * or a NULL file handle if the file was not a part of this translation unit.
339  */
340 CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu,
341  const char *file_name);
342 
343 /**
344  * \brief Returns non-zero if the \c file1 and \c file2 point to the same file,
345  * or they are both NULL.
346  */
347 CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2);
348 
349 /**
350  * @}
351  */
352 
353 /**
354  * \defgroup CINDEX_LOCATIONS Physical source locations
355  *
356  * Clang represents physical source locations in its abstract syntax tree in
357  * great detail, with file, line, and column information for the majority of
358  * the tokens parsed in the source code. These data types and functions are
359  * used to represent source location information, either for a particular
360  * point in the program or for a range of points in the program, and extract
361  * specific location information from those data types.
362  *
363  * @{
364  */
365 
366 /**
367  * \brief Identifies a specific source location within a translation
368  * unit.
369  *
370  * Use clang_getExpansionLocation() or clang_getSpellingLocation()
371  * to map a source location to a particular file, line, and column.
372  */
373 typedef struct {
374  const void *ptr_data[2];
375  unsigned int_data;
377 
378 /**
379  * \brief Identifies a half-open character range in the source code.
380  *
381  * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
382  * starting and end locations from a source range, respectively.
383  */
384 typedef struct {
385  const void *ptr_data[2];
386  unsigned begin_int_data;
387  unsigned end_int_data;
388 } CXSourceRange;
389 
390 /**
391  * \brief Retrieve a NULL (invalid) source location.
392  */
394 
395 /**
396  * \brief Determine whether two source locations, which must refer into
397  * the same translation unit, refer to exactly the same point in the source
398  * code.
399  *
400  * \returns non-zero if the source locations refer to the same location, zero
401  * if they refer to different locations.
402  */
404  CXSourceLocation loc2);
405 
406 /**
407  * \brief Retrieves the source location associated with a given file/line/column
408  * in a particular translation unit.
409  */
411  CXFile file,
412  unsigned line,
413  unsigned column);
414 /**
415  * \brief Retrieves the source location associated with a given character offset
416  * in a particular translation unit.
417  */
419  CXFile file,
420  unsigned offset);
421 
422 /**
423  * \brief Returns non-zero if the given source location is in a system header.
424  */
426 
427 /**
428  * \brief Returns non-zero if the given source location is in the main file of
429  * the corresponding translation unit.
430  */
432 
433 /**
434  * \brief Retrieve a NULL (invalid) source range.
435  */
437 
438 /**
439  * \brief Retrieve a source range given the beginning and ending source
440  * locations.
441  */
443  CXSourceLocation end);
444 
445 /**
446  * \brief Determine whether two ranges are equivalent.
447  *
448  * \returns non-zero if the ranges are the same, zero if they differ.
449  */
451  CXSourceRange range2);
452 
453 /**
454  * \brief Returns non-zero if \p range is null.
455  */
457 
458 /**
459  * \brief Retrieve the file, line, column, and offset represented by
460  * the given source location.
461  *
462  * If the location refers into a macro expansion, retrieves the
463  * location of the macro expansion.
464  *
465  * \param location the location within a source file that will be decomposed
466  * into its parts.
467  *
468  * \param file [out] if non-NULL, will be set to the file to which the given
469  * source location points.
470  *
471  * \param line [out] if non-NULL, will be set to the line to which the given
472  * source location points.
473  *
474  * \param column [out] if non-NULL, will be set to the column to which the given
475  * source location points.
476  *
477  * \param offset [out] if non-NULL, will be set to the offset into the
478  * buffer to which the given source location points.
479  */
481  CXFile *file,
482  unsigned *line,
483  unsigned *column,
484  unsigned *offset);
485 
486 /**
487  * \brief Retrieve the file, line and column represented by the given source
488  * location, as specified in a # line directive.
489  *
490  * Example: given the following source code in a file somefile.c
491  *
492  * \code
493  * #123 "dummy.c" 1
494  *
495  * static int func(void)
496  * {
497  * return 0;
498  * }
499  * \endcode
500  *
501  * the location information returned by this function would be
502  *
503  * File: dummy.c Line: 124 Column: 12
504  *
505  * whereas clang_getExpansionLocation would have returned
506  *
507  * File: somefile.c Line: 3 Column: 12
508  *
509  * \param location the location within a source file that will be decomposed
510  * into its parts.
511  *
512  * \param filename [out] if non-NULL, will be set to the filename of the
513  * source location. Note that filenames returned will be for "virtual" files,
514  * which don't necessarily exist on the machine running clang - e.g. when
515  * parsing preprocessed output obtained from a different environment. If
516  * a non-NULL value is passed in, remember to dispose of the returned value
517  * using \c clang_disposeString() once you've finished with it. For an invalid
518  * source location, an empty string is returned.
519  *
520  * \param line [out] if non-NULL, will be set to the line number of the
521  * source location. For an invalid source location, zero is returned.
522  *
523  * \param column [out] if non-NULL, will be set to the column number of the
524  * source location. For an invalid source location, zero is returned.
525  */
527  CXString *filename,
528  unsigned *line,
529  unsigned *column);
530 
531 /**
532  * \brief Legacy API to retrieve the file, line, column, and offset represented
533  * by the given source location.
534  *
535  * This interface has been replaced by the newer interface
536  * #clang_getExpansionLocation(). See that interface's documentation for
537  * details.
538  */
540  CXFile *file,
541  unsigned *line,
542  unsigned *column,
543  unsigned *offset);
544 
545 /**
546  * \brief Retrieve the file, line, column, and offset represented by
547  * the given source location.
548  *
549  * If the location refers into a macro instantiation, return where the
550  * location was originally spelled in the source file.
551  *
552  * \param location the location within a source file that will be decomposed
553  * into its parts.
554  *
555  * \param file [out] if non-NULL, will be set to the file to which the given
556  * source location points.
557  *
558  * \param line [out] if non-NULL, will be set to the line to which the given
559  * source location points.
560  *
561  * \param column [out] if non-NULL, will be set to the column to which the given
562  * source location points.
563  *
564  * \param offset [out] if non-NULL, will be set to the offset into the
565  * buffer to which the given source location points.
566  */
568  CXFile *file,
569  unsigned *line,
570  unsigned *column,
571  unsigned *offset);
572 
573 /**
574  * \brief Retrieve the file, line, column, and offset represented by
575  * the given source location.
576  *
577  * If the location refers into a macro expansion, return where the macro was
578  * expanded or where the macro argument was written, if the location points at
579  * a macro argument.
580  *
581  * \param location the location within a source file that will be decomposed
582  * into its parts.
583  *
584  * \param file [out] if non-NULL, will be set to the file to which the given
585  * source location points.
586  *
587  * \param line [out] if non-NULL, will be set to the line to which the given
588  * source location points.
589  *
590  * \param column [out] if non-NULL, will be set to the column to which the given
591  * source location points.
592  *
593  * \param offset [out] if non-NULL, will be set to the offset into the
594  * buffer to which the given source location points.
595  */
597  CXFile *file,
598  unsigned *line,
599  unsigned *column,
600  unsigned *offset);
601 
602 /**
603  * \brief Retrieve a source location representing the first character within a
604  * source range.
605  */
607 
608 /**
609  * \brief Retrieve a source location representing the last character within a
610  * source range.
611  */
613 
614 /**
615  * \brief Identifies an array of ranges.
616  */
617 typedef struct {
618  /** \brief The number of ranges in the \c ranges array. */
619  unsigned count;
620  /**
621  * \brief An array of \c CXSourceRanges.
622  */
625 
626 /**
627  * \brief Retrieve all ranges that were skipped by the preprocessor.
628  *
629  * The preprocessor will skip lines when they are surrounded by an
630  * if/ifdef/ifndef directive whose condition does not evaluate to true.
631  */
633  CXFile file);
634 
635 /**
636  * \brief Retrieve all ranges from all files that were skipped by the
637  * preprocessor.
638  *
639  * The preprocessor will skip lines when they are surrounded by an
640  * if/ifdef/ifndef directive whose condition does not evaluate to true.
641  */
643 
644 /**
645  * \brief Destroy the given \c CXSourceRangeList.
646  */
648 
649 /**
650  * @}
651  */
652 
653 /**
654  * \defgroup CINDEX_DIAG Diagnostic reporting
655  *
656  * @{
657  */
658 
659 /**
660  * \brief Describes the severity of a particular diagnostic.
661  */
663  /**
664  * \brief A diagnostic that has been suppressed, e.g., by a command-line
665  * option.
666  */
668 
669  /**
670  * \brief This diagnostic is a note that should be attached to the
671  * previous (non-note) diagnostic.
672  */
674 
675  /**
676  * \brief This diagnostic indicates suspicious code that may not be
677  * wrong.
678  */
680 
681  /**
682  * \brief This diagnostic indicates that the code is ill-formed.
683  */
685 
686  /**
687  * \brief This diagnostic indicates that the code is ill-formed such
688  * that future parser recovery is unlikely to produce useful
689  * results.
690  */
692 };
693 
694 /**
695  * \brief A single diagnostic, containing the diagnostic's severity,
696  * location, text, source ranges, and fix-it hints.
697  */
698 typedef void *CXDiagnostic;
699 
700 /**
701  * \brief A group of CXDiagnostics.
702  */
703 typedef void *CXDiagnosticSet;
704 
705 /**
706  * \brief Determine the number of diagnostics in a CXDiagnosticSet.
707  */
708 CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);
709 
710 /**
711  * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet.
712  *
713  * \param Diags the CXDiagnosticSet to query.
714  * \param Index the zero-based diagnostic number to retrieve.
715  *
716  * \returns the requested diagnostic. This diagnostic must be freed
717  * via a call to \c clang_disposeDiagnostic().
718  */
719 CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,
720  unsigned Index);
721 
722 /**
723  * \brief Describes the kind of error that occurred (if any) in a call to
724  * \c clang_loadDiagnostics.
725  */
727  /**
728  * \brief Indicates that no error occurred.
729  */
731 
732  /**
733  * \brief Indicates that an unknown error occurred while attempting to
734  * deserialize diagnostics.
735  */
737 
738  /**
739  * \brief Indicates that the file containing the serialized diagnostics
740  * could not be opened.
741  */
743 
744  /**
745  * \brief Indicates that the serialized diagnostics file is invalid or
746  * corrupt.
747  */
749 };
750 
751 /**
752  * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode
753  * file.
754  *
755  * \param file The name of the file to deserialize.
756  * \param error A pointer to a enum value recording if there was a problem
757  * deserializing the diagnostics.
758  * \param errorString A pointer to a CXString for recording the error string
759  * if the file was not successfully loaded.
760  *
761  * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These
762  * diagnostics should be released using clang_disposeDiagnosticSet().
763  */
764 CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file,
765  enum CXLoadDiag_Error *error,
766  CXString *errorString);
767 
768 /**
769  * \brief Release a CXDiagnosticSet and all of its contained diagnostics.
770  */
771 CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);
772 
773 /**
774  * \brief Retrieve the child diagnostics of a CXDiagnostic.
775  *
776  * This CXDiagnosticSet does not need to be released by
777  * clang_disposeDiagnosticSet.
778  */
779 CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);
780 
781 /**
782  * \brief Determine the number of diagnostics produced for the given
783  * translation unit.
784  */
785 CINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit);
786 
787 /**
788  * \brief Retrieve a diagnostic associated with the given translation unit.
789  *
790  * \param Unit the translation unit to query.
791  * \param Index the zero-based diagnostic number to retrieve.
792  *
793  * \returns the requested diagnostic. This diagnostic must be freed
794  * via a call to \c clang_disposeDiagnostic().
795  */
796 CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit,
797  unsigned Index);
798 
799 /**
800  * \brief Retrieve the complete set of diagnostics associated with a
801  * translation unit.
802  *
803  * \param Unit the translation unit to query.
804  */
805 CINDEX_LINKAGE CXDiagnosticSet
806  clang_getDiagnosticSetFromTU(CXTranslationUnit Unit);
807 
808 /**
809  * \brief Destroy a diagnostic.
810  */
811 CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
812 
813 /**
814  * \brief Options to control the display of diagnostics.
815  *
816  * The values in this enum are meant to be combined to customize the
817  * behavior of \c clang_formatDiagnostic().
818  */
820  /**
821  * \brief Display the source-location information where the
822  * diagnostic was located.
823  *
824  * When set, diagnostics will be prefixed by the file, line, and
825  * (optionally) column to which the diagnostic refers. For example,
826  *
827  * \code
828  * test.c:28: warning: extra tokens at end of #endif directive
829  * \endcode
830  *
831  * This option corresponds to the clang flag \c -fshow-source-location.
832  */
834 
835  /**
836  * \brief If displaying the source-location information of the
837  * diagnostic, also include the column number.
838  *
839  * This option corresponds to the clang flag \c -fshow-column.
840  */
842 
843  /**
844  * \brief If displaying the source-location information of the
845  * diagnostic, also include information about source ranges in a
846  * machine-parsable format.
847  *
848  * This option corresponds to the clang flag
849  * \c -fdiagnostics-print-source-range-info.
850  */
852 
853  /**
854  * \brief Display the option name associated with this diagnostic, if any.
855  *
856  * The option name displayed (e.g., -Wconversion) will be placed in brackets
857  * after the diagnostic text. This option corresponds to the clang flag
858  * \c -fdiagnostics-show-option.
859  */
861 
862  /**
863  * \brief Display the category number associated with this diagnostic, if any.
864  *
865  * The category number is displayed within brackets after the diagnostic text.
866  * This option corresponds to the clang flag
867  * \c -fdiagnostics-show-category=id.
868  */
870 
871  /**
872  * \brief Display the category name associated with this diagnostic, if any.
873  *
874  * The category name is displayed within brackets after the diagnostic text.
875  * This option corresponds to the clang flag
876  * \c -fdiagnostics-show-category=name.
877  */
879 };
880 
881 /**
882  * \brief Format the given diagnostic in a manner that is suitable for display.
883  *
884  * This routine will format the given diagnostic to a string, rendering
885  * the diagnostic according to the various options given. The
886  * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
887  * options that most closely mimics the behavior of the clang compiler.
888  *
889  * \param Diagnostic The diagnostic to print.
890  *
891  * \param Options A set of options that control the diagnostic display,
892  * created by combining \c CXDiagnosticDisplayOptions values.
893  *
894  * \returns A new string containing for formatted diagnostic.
895  */
896 CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
897  unsigned Options);
898 
899 /**
900  * \brief Retrieve the set of display options most similar to the
901  * default behavior of the clang compiler.
902  *
903  * \returns A set of display options suitable for use with \c
904  * clang_formatDiagnostic().
905  */
907 
908 /**
909  * \brief Determine the severity of the given diagnostic.
910  */
912 clang_getDiagnosticSeverity(CXDiagnostic);
913 
914 /**
915  * \brief Retrieve the source location of the given diagnostic.
916  *
917  * This location is where Clang would print the caret ('^') when
918  * displaying the diagnostic on the command line.
919  */
921 
922 /**
923  * \brief Retrieve the text of the given diagnostic.
924  */
926 
927 /**
928  * \brief Retrieve the name of the command-line option that enabled this
929  * diagnostic.
930  *
931  * \param Diag The diagnostic to be queried.
932  *
933  * \param Disable If non-NULL, will be set to the option that disables this
934  * diagnostic (if any).
935  *
936  * \returns A string that contains the command-line option used to enable this
937  * warning, such as "-Wconversion" or "-pedantic".
938  */
940  CXString *Disable);
941 
942 /**
943  * \brief Retrieve the category number for this diagnostic.
944  *
945  * Diagnostics can be categorized into groups along with other, related
946  * diagnostics (e.g., diagnostics under the same warning flag). This routine
947  * retrieves the category number for the given diagnostic.
948  *
949  * \returns The number of the category that contains this diagnostic, or zero
950  * if this diagnostic is uncategorized.
951  */
952 CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);
953 
954 /**
955  * \brief Retrieve the name of a particular diagnostic category. This
956  * is now deprecated. Use clang_getDiagnosticCategoryText()
957  * instead.
958  *
959  * \param Category A diagnostic category number, as returned by
960  * \c clang_getDiagnosticCategory().
961  *
962  * \returns The name of the given diagnostic category.
963  */
966 
967 /**
968  * \brief Retrieve the diagnostic category text for a given diagnostic.
969  *
970  * \returns The text of the given diagnostic category.
971  */
973 
974 /**
975  * \brief Determine the number of source ranges associated with the given
976  * diagnostic.
977  */
978 CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
979 
980 /**
981  * \brief Retrieve a source range associated with the diagnostic.
982  *
983  * A diagnostic's source ranges highlight important elements in the source
984  * code. On the command line, Clang displays source ranges by
985  * underlining them with '~' characters.
986  *
987  * \param Diagnostic the diagnostic whose range is being extracted.
988  *
989  * \param Range the zero-based index specifying which range to
990  *
991  * \returns the requested source range.
992  */
994  unsigned Range);
995 
996 /**
997  * \brief Determine the number of fix-it hints associated with the
998  * given diagnostic.
999  */
1000 CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
1001 
1002 /**
1003  * \brief Retrieve the replacement information for a given fix-it.
1004  *
1005  * Fix-its are described in terms of a source range whose contents
1006  * should be replaced by a string. This approach generalizes over
1007  * three kinds of operations: removal of source code (the range covers
1008  * the code to be removed and the replacement string is empty),
1009  * replacement of source code (the range covers the code to be
1010  * replaced and the replacement string provides the new code), and
1011  * insertion (both the start and end of the range point at the
1012  * insertion location, and the replacement string provides the text to
1013  * insert).
1014  *
1015  * \param Diagnostic The diagnostic whose fix-its are being queried.
1016  *
1017  * \param FixIt The zero-based index of the fix-it.
1018  *
1019  * \param ReplacementRange The source range whose contents will be
1020  * replaced with the returned replacement string. Note that source
1021  * ranges are half-open ranges [a, b), so the source code should be
1022  * replaced from a and up to (but not including) b.
1023  *
1024  * \returns A string containing text that should be replace the source
1025  * code indicated by the \c ReplacementRange.
1026  */
1027 CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic,
1028  unsigned FixIt,
1029  CXSourceRange *ReplacementRange);
1030 
1031 /**
1032  * @}
1033  */
1034 
1035 /**
1036  * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
1037  *
1038  * The routines in this group provide the ability to create and destroy
1039  * translation units from files, either by parsing the contents of the files or
1040  * by reading in a serialized representation of a translation unit.
1041  *
1042  * @{
1043  */
1044 
1045 /**
1046  * \brief Get the original translation unit source file name.
1047  */
1049 clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit);
1050 
1051 /**
1052  * \brief Return the CXTranslationUnit for a given source file and the provided
1053  * command line arguments one would pass to the compiler.
1054  *
1055  * Note: The 'source_filename' argument is optional. If the caller provides a
1056  * NULL pointer, the name of the source file is expected to reside in the
1057  * specified command line arguments.
1058  *
1059  * Note: When encountered in 'clang_command_line_args', the following options
1060  * are ignored:
1061  *
1062  * '-c'
1063  * '-emit-ast'
1064  * '-fsyntax-only'
1065  * '-o <output file>' (both '-o' and '<output file>' are ignored)
1066  *
1067  * \param CIdx The index object with which the translation unit will be
1068  * associated.
1069  *
1070  * \param source_filename The name of the source file to load, or NULL if the
1071  * source file is included in \p clang_command_line_args.
1072  *
1073  * \param num_clang_command_line_args The number of command-line arguments in
1074  * \p clang_command_line_args.
1075  *
1076  * \param clang_command_line_args The command-line arguments that would be
1077  * passed to the \c clang executable if it were being invoked out-of-process.
1078  * These command-line options will be parsed and will affect how the translation
1079  * unit is parsed. Note that the following options are ignored: '-c',
1080  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.
1081  *
1082  * \param num_unsaved_files the number of unsaved file entries in \p
1083  * unsaved_files.
1084  *
1085  * \param unsaved_files the files that have not yet been saved to disk
1086  * but may be required for code completion, including the contents of
1087  * those files. The contents and name of these files (as specified by
1088  * CXUnsavedFile) are copied when necessary, so the client only needs to
1089  * guarantee their validity until the call to this function returns.
1090  */
1092  CXIndex CIdx,
1093  const char *source_filename,
1094  int num_clang_command_line_args,
1095  const char * const *clang_command_line_args,
1096  unsigned num_unsaved_files,
1097  struct CXUnsavedFile *unsaved_files);
1098 
1099 /**
1100  * \brief Same as \c clang_createTranslationUnit2, but returns
1101  * the \c CXTranslationUnit instead of an error code. In case of an error this
1102  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
1103  * error codes.
1104  */
1106  CXIndex CIdx,
1107  const char *ast_filename);
1108 
1109 /**
1110  * \brief Create a translation unit from an AST file (\c -emit-ast).
1111  *
1112  * \param[out] out_TU A non-NULL pointer to store the created
1113  * \c CXTranslationUnit.
1114  *
1115  * \returns Zero on success, otherwise returns an error code.
1116  */
1118  CXIndex CIdx,
1119  const char *ast_filename,
1120  CXTranslationUnit *out_TU);
1121 
1122 /**
1123  * \brief Flags that control the creation of translation units.
1124  *
1125  * The enumerators in this enumeration type are meant to be bitwise
1126  * ORed together to specify which options should be used when
1127  * constructing the translation unit.
1128  */
1130  /**
1131  * \brief Used to indicate that no special translation-unit options are
1132  * needed.
1133  */
1135 
1136  /**
1137  * \brief Used to indicate that the parser should construct a "detailed"
1138  * preprocessing record, including all macro definitions and instantiations.
1139  *
1140  * Constructing a detailed preprocessing record requires more memory
1141  * and time to parse, since the information contained in the record
1142  * is usually not retained. However, it can be useful for
1143  * applications that require more detailed information about the
1144  * behavior of the preprocessor.
1145  */
1147 
1148  /**
1149  * \brief Used to indicate that the translation unit is incomplete.
1150  *
1151  * When a translation unit is considered "incomplete", semantic
1152  * analysis that is typically performed at the end of the
1153  * translation unit will be suppressed. For example, this suppresses
1154  * the completion of tentative declarations in C and of
1155  * instantiation of implicitly-instantiation function templates in
1156  * C++. This option is typically used when parsing a header with the
1157  * intent of producing a precompiled header.
1158  */
1160 
1161  /**
1162  * \brief Used to indicate that the translation unit should be built with an
1163  * implicit precompiled header for the preamble.
1164  *
1165  * An implicit precompiled header is used as an optimization when a
1166  * particular translation unit is likely to be reparsed many times
1167  * when the sources aren't changing that often. In this case, an
1168  * implicit precompiled header will be built containing all of the
1169  * initial includes at the top of the main file (what we refer to as
1170  * the "preamble" of the file). In subsequent parses, if the
1171  * preamble or the files in it have not changed, \c
1172  * clang_reparseTranslationUnit() will re-use the implicit
1173  * precompiled header to improve parsing performance.
1174  */
1176 
1177  /**
1178  * \brief Used to indicate that the translation unit should cache some
1179  * code-completion results with each reparse of the source file.
1180  *
1181  * Caching of code-completion results is a performance optimization that
1182  * introduces some overhead to reparsing but improves the performance of
1183  * code-completion operations.
1184  */
1186 
1187  /**
1188  * \brief Used to indicate that the translation unit will be serialized with
1189  * \c clang_saveTranslationUnit.
1190  *
1191  * This option is typically used when parsing a header with the intent of
1192  * producing a precompiled header.
1193  */
1195 
1196  /**
1197  * \brief DEPRECATED: Enabled chained precompiled preambles in C++.
1198  *
1199  * Note: this is a *temporary* option that is available only while
1200  * we are testing C++ precompiled preamble support. It is deprecated.
1201  */
1203 
1204  /**
1205  * \brief Used to indicate that function/method bodies should be skipped while
1206  * parsing.
1207  *
1208  * This option can be used to search for declarations/definitions while
1209  * ignoring the usages.
1210  */
1212 
1213  /**
1214  * \brief Used to indicate that brief documentation comments should be
1215  * included into the set of code completions returned from this translation
1216  * unit.
1217  */
1219 
1220  /**
1221  * \brief Used to indicate that the precompiled preamble should be created on
1222  * the first parse. Otherwise it will be created on the first reparse. This
1223  * trades runtime on the first parse (serializing the preamble takes time) for
1224  * reduced runtime on the second parse (can now reuse the preamble).
1225  */
1227 
1228  /**
1229  * \brief Do not stop processing when fatal errors are encountered.
1230  *
1231  * When fatal errors are encountered while parsing a translation unit,
1232  * semantic analysis is typically stopped early when compiling code. A common
1233  * source for fatal errors are unresolvable include files. For the
1234  * purposes of an IDE, this is undesirable behavior and as much information
1235  * as possible should be reported. Use this flag to enable this behavior.
1236  */
1238 
1239  /**
1240  * \brief Sets the preprocessor in a mode for parsing a single file only.
1241  */
1243 };
1244 
1245 /**
1246  * \brief Returns the set of flags that is suitable for parsing a translation
1247  * unit that is being edited.
1248  *
1249  * The set of flags returned provide options for \c clang_parseTranslationUnit()
1250  * to indicate that the translation unit is likely to be reparsed many times,
1251  * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
1252  * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
1253  * set contains an unspecified set of optimizations (e.g., the precompiled
1254  * preamble) geared toward improving the performance of these routines. The
1255  * set of optimizations enabled may change from one version to the next.
1256  */
1258 
1259 /**
1260  * \brief Same as \c clang_parseTranslationUnit2, but returns
1261  * the \c CXTranslationUnit instead of an error code. In case of an error this
1262  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
1263  * error codes.
1264  */
1265 CINDEX_LINKAGE CXTranslationUnit
1266 clang_parseTranslationUnit(CXIndex CIdx,
1267  const char *source_filename,
1268  const char *const *command_line_args,
1269  int num_command_line_args,
1270  struct CXUnsavedFile *unsaved_files,
1271  unsigned num_unsaved_files,
1272  unsigned options);
1273 
1274 /**
1275  * \brief Parse the given source file and the translation unit corresponding
1276  * to that file.
1277  *
1278  * This routine is the main entry point for the Clang C API, providing the
1279  * ability to parse a source file into a translation unit that can then be
1280  * queried by other functions in the API. This routine accepts a set of
1281  * command-line arguments so that the compilation can be configured in the same
1282  * way that the compiler is configured on the command line.
1283  *
1284  * \param CIdx The index object with which the translation unit will be
1285  * associated.
1286  *
1287  * \param source_filename The name of the source file to load, or NULL if the
1288  * source file is included in \c command_line_args.
1289  *
1290  * \param command_line_args The command-line arguments that would be
1291  * passed to the \c clang executable if it were being invoked out-of-process.
1292  * These command-line options will be parsed and will affect how the translation
1293  * unit is parsed. Note that the following options are ignored: '-c',
1294  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.
1295  *
1296  * \param num_command_line_args The number of command-line arguments in
1297  * \c command_line_args.
1298  *
1299  * \param unsaved_files the files that have not yet been saved to disk
1300  * but may be required for parsing, including the contents of
1301  * those files. The contents and name of these files (as specified by
1302  * CXUnsavedFile) are copied when necessary, so the client only needs to
1303  * guarantee their validity until the call to this function returns.
1304  *
1305  * \param num_unsaved_files the number of unsaved file entries in \p
1306  * unsaved_files.
1307  *
1308  * \param options A bitmask of options that affects how the translation unit
1309  * is managed but not its compilation. This should be a bitwise OR of the
1310  * CXTranslationUnit_XXX flags.
1311  *
1312  * \param[out] out_TU A non-NULL pointer to store the created
1313  * \c CXTranslationUnit, describing the parsed code and containing any
1314  * diagnostics produced by the compiler.
1315  *
1316  * \returns Zero on success, otherwise returns an error code.
1317  */
1319 clang_parseTranslationUnit2(CXIndex CIdx,
1320  const char *source_filename,
1321  const char *const *command_line_args,
1322  int num_command_line_args,
1323  struct CXUnsavedFile *unsaved_files,
1324  unsigned num_unsaved_files,
1325  unsigned options,
1326  CXTranslationUnit *out_TU);
1327 
1328 /**
1329  * \brief Same as clang_parseTranslationUnit2 but requires a full command line
1330  * for \c command_line_args including argv[0]. This is useful if the standard
1331  * library paths are relative to the binary.
1332  */
1334  CXIndex CIdx, const char *source_filename,
1335  const char *const *command_line_args, int num_command_line_args,
1336  struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
1337  unsigned options, CXTranslationUnit *out_TU);
1338 
1339 /**
1340  * \brief Flags that control how translation units are saved.
1341  *
1342  * The enumerators in this enumeration type are meant to be bitwise
1343  * ORed together to specify which options should be used when
1344  * saving the translation unit.
1345  */
1347  /**
1348  * \brief Used to indicate that no special saving options are needed.
1349  */
1351 };
1352 
1353 /**
1354  * \brief Returns the set of flags that is suitable for saving a translation
1355  * unit.
1356  *
1357  * The set of flags returned provide options for
1358  * \c clang_saveTranslationUnit() by default. The returned flag
1359  * set contains an unspecified set of options that save translation units with
1360  * the most commonly-requested data.
1361  */
1362 CINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU);
1363 
1364 /**
1365  * \brief Describes the kind of error that occurred (if any) in a call to
1366  * \c clang_saveTranslationUnit().
1367  */
1369  /**
1370  * \brief Indicates that no error occurred while saving a translation unit.
1371  */
1373 
1374  /**
1375  * \brief Indicates that an unknown error occurred while attempting to save
1376  * the file.
1377  *
1378  * This error typically indicates that file I/O failed when attempting to
1379  * write the file.
1380  */
1382 
1383  /**
1384  * \brief Indicates that errors during translation prevented this attempt
1385  * to save the translation unit.
1386  *
1387  * Errors that prevent the translation unit from being saved can be
1388  * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic().
1389  */
1391 
1392  /**
1393  * \brief Indicates that the translation unit to be saved was somehow
1394  * invalid (e.g., NULL).
1395  */
1397 };
1398 
1399 /**
1400  * \brief Saves a translation unit into a serialized representation of
1401  * that translation unit on disk.
1402  *
1403  * Any translation unit that was parsed without error can be saved
1404  * into a file. The translation unit can then be deserialized into a
1405  * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
1406  * if it is an incomplete translation unit that corresponds to a
1407  * header, used as a precompiled header when parsing other translation
1408  * units.
1409  *
1410  * \param TU The translation unit to save.
1411  *
1412  * \param FileName The file to which the translation unit will be saved.
1413  *
1414  * \param options A bitmask of options that affects how the translation unit
1415  * is saved. This should be a bitwise OR of the
1416  * CXSaveTranslationUnit_XXX flags.
1417  *
1418  * \returns A value that will match one of the enumerators of the CXSaveError
1419  * enumeration. Zero (CXSaveError_None) indicates that the translation unit was
1420  * saved successfully, while a non-zero value indicates that a problem occurred.
1421  */
1422 CINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU,
1423  const char *FileName,
1424  unsigned options);
1425 
1426 /**
1427  * \brief Suspend a translation unit in order to free memory associated with it.
1428  *
1429  * A suspended translation unit uses significantly less memory but on the other
1430  * side does not support any other calls than \c clang_reparseTranslationUnit
1431  * to resume it or \c clang_disposeTranslationUnit to dispose it completely.
1432  */
1433 CINDEX_LINKAGE unsigned clang_suspendTranslationUnit(CXTranslationUnit);
1434 
1435 /**
1436  * \brief Destroy the specified CXTranslationUnit object.
1437  */
1438 CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit);
1439 
1440 /**
1441  * \brief Flags that control the reparsing of translation units.
1442  *
1443  * The enumerators in this enumeration type are meant to be bitwise
1444  * ORed together to specify which options should be used when
1445  * reparsing the translation unit.
1446  */
1448  /**
1449  * \brief Used to indicate that no special reparsing options are needed.
1450  */
1452 };
1453 
1454 /**
1455  * \brief Returns the set of flags that is suitable for reparsing a translation
1456  * unit.
1457  *
1458  * The set of flags returned provide options for
1459  * \c clang_reparseTranslationUnit() by default. The returned flag
1460  * set contains an unspecified set of optimizations geared toward common uses
1461  * of reparsing. The set of optimizations enabled may change from one version
1462  * to the next.
1463  */
1464 CINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU);
1465 
1466 /**
1467  * \brief Reparse the source files that produced this translation unit.
1468  *
1469  * This routine can be used to re-parse the source files that originally
1470  * created the given translation unit, for example because those source files
1471  * have changed (either on disk or as passed via \p unsaved_files). The
1472  * source code will be reparsed with the same command-line options as it
1473  * was originally parsed.
1474  *
1475  * Reparsing a translation unit invalidates all cursors and source locations
1476  * that refer into that translation unit. This makes reparsing a translation
1477  * unit semantically equivalent to destroying the translation unit and then
1478  * creating a new translation unit with the same command-line arguments.
1479  * However, it may be more efficient to reparse a translation
1480  * unit using this routine.
1481  *
1482  * \param TU The translation unit whose contents will be re-parsed. The
1483  * translation unit must originally have been built with
1484  * \c clang_createTranslationUnitFromSourceFile().
1485  *
1486  * \param num_unsaved_files The number of unsaved file entries in \p
1487  * unsaved_files.
1488  *
1489  * \param unsaved_files The files that have not yet been saved to disk
1490  * but may be required for parsing, including the contents of
1491  * those files. The contents and name of these files (as specified by
1492  * CXUnsavedFile) are copied when necessary, so the client only needs to
1493  * guarantee their validity until the call to this function returns.
1494  *
1495  * \param options A bitset of options composed of the flags in CXReparse_Flags.
1496  * The function \c clang_defaultReparseOptions() produces a default set of
1497  * options recommended for most uses, based on the translation unit.
1498  *
1499  * \returns 0 if the sources could be reparsed. A non-zero error code will be
1500  * returned if reparsing was impossible, such that the translation unit is
1501  * invalid. In such cases, the only valid call for \c TU is
1502  * \c clang_disposeTranslationUnit(TU). The error codes returned by this
1503  * routine are described by the \c CXErrorCode enum.
1504  */
1505 CINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU,
1506  unsigned num_unsaved_files,
1507  struct CXUnsavedFile *unsaved_files,
1508  unsigned options);
1509 
1510 /**
1511  * \brief Categorizes how memory is being used by a translation unit.
1512  */
1531 
1534 };
1535 
1536 /**
1537  * \brief Returns the human-readable null-terminated C string that represents
1538  * the name of the memory category. This string should never be freed.
1539  */
1542 
1543 typedef struct CXTUResourceUsageEntry {
1544  /* \brief The memory usage category. */
1546  /* \brief Amount of resources used.
1547  The units will depend on the resource kind. */
1548  unsigned long amount;
1550 
1551 /**
1552  * \brief The memory usage of a CXTranslationUnit, broken into categories.
1553  */
1554 typedef struct CXTUResourceUsage {
1555  /* \brief Private data member, used for queries. */
1556  void *data;
1557 
1558  /* \brief The number of entries in the 'entries' array. */
1559  unsigned numEntries;
1560 
1561  /* \brief An array of key-value pairs, representing the breakdown of memory
1562  usage. */
1564 
1566 
1567 /**
1568  * \brief Return the memory usage of a translation unit. This object
1569  * should be released with clang_disposeCXTUResourceUsage().
1570  */
1572 
1574 
1575 /**
1576  * \brief Get target information for this translation unit.
1577  *
1578  * The CXTargetInfo object cannot outlive the CXTranslationUnit object.
1579  */
1580 CINDEX_LINKAGE CXTargetInfo
1581 clang_getTranslationUnitTargetInfo(CXTranslationUnit CTUnit);
1582 
1583 /**
1584  * \brief Destroy the CXTargetInfo object.
1585  */
1586 CINDEX_LINKAGE void
1587 clang_TargetInfo_dispose(CXTargetInfo Info);
1588 
1589 /**
1590  * \brief Get the normalized target triple as a string.
1591  *
1592  * Returns the empty string in case of any error.
1593  */
1595 clang_TargetInfo_getTriple(CXTargetInfo Info);
1596 
1597 /**
1598  * \brief Get the pointer width of the target in bits.
1599  *
1600  * Returns -1 in case of error.
1601  */
1602 CINDEX_LINKAGE int
1603 clang_TargetInfo_getPointerWidth(CXTargetInfo Info);
1604 
1605 /**
1606  * @}
1607  */
1608 
1609 /**
1610  * \brief Describes the kind of entity that a cursor refers to.
1611  */
1613  /* Declarations */
1614  /**
1615  * \brief A declaration whose specific kind is not exposed via this
1616  * interface.
1617  *
1618  * Unexposed declarations have the same operations as any other kind
1619  * of declaration; one can extract their location information,
1620  * spelling, find their definitions, etc. However, the specific kind
1621  * of the declaration is not reported.
1622  */
1624  /** \brief A C or C++ struct. */
1626  /** \brief A C or C++ union. */
1628  /** \brief A C++ class. */
1630  /** \brief An enumeration. */
1632  /**
1633  * \brief A field (in C) or non-static data member (in C++) in a
1634  * struct, union, or C++ class.
1635  */
1637  /** \brief An enumerator constant. */
1639  /** \brief A function. */
1641  /** \brief A variable. */
1643  /** \brief A function or method parameter. */
1645  /** \brief An Objective-C \@interface. */
1647  /** \brief An Objective-C \@interface for a category. */
1649  /** \brief An Objective-C \@protocol declaration. */
1651  /** \brief An Objective-C \@property declaration. */
1653  /** \brief An Objective-C instance variable. */
1655  /** \brief An Objective-C instance method. */
1657  /** \brief An Objective-C class method. */
1659  /** \brief An Objective-C \@implementation. */
1661  /** \brief An Objective-C \@implementation for a category. */
1663  /** \brief A typedef. */
1665  /** \brief A C++ class method. */
1667  /** \brief A C++ namespace. */
1669  /** \brief A linkage specification, e.g. 'extern "C"'. */
1671  /** \brief A C++ constructor. */
1673  /** \brief A C++ destructor. */
1675  /** \brief A C++ conversion function. */
1677  /** \brief A C++ template type parameter. */
1679  /** \brief A C++ non-type template parameter. */
1681  /** \brief A C++ template template parameter. */
1683  /** \brief A C++ function template. */
1685  /** \brief A C++ class template. */
1687  /** \brief A C++ class template partial specialization. */
1689  /** \brief A C++ namespace alias declaration. */
1691  /** \brief A C++ using directive. */
1693  /** \brief A C++ using declaration. */
1695  /** \brief A C++ alias declaration */
1697  /** \brief An Objective-C \@synthesize definition. */
1699  /** \brief An Objective-C \@dynamic definition. */
1701  /** \brief An access specifier. */
1703 
1706 
1707  /* References */
1708  CXCursor_FirstRef = 40, /* Decl references */
1712  /**
1713  * \brief A reference to a type declaration.
1714  *
1715  * A type reference occurs anywhere where a type is named but not
1716  * declared. For example, given:
1717  *
1718  * \code
1719  * typedef unsigned size_type;
1720  * size_type size;
1721  * \endcode
1722  *
1723  * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
1724  * while the type of the variable "size" is referenced. The cursor
1725  * referenced by the type of size is the typedef for size_type.
1726  */
1729  /**
1730  * \brief A reference to a class template, function template, template
1731  * template parameter, or class template partial specialization.
1732  */
1734  /**
1735  * \brief A reference to a namespace or namespace alias.
1736  */
1738  /**
1739  * \brief A reference to a member of a struct, union, or class that occurs in
1740  * some non-expression context, e.g., a designated initializer.
1741  */
1743  /**
1744  * \brief A reference to a labeled statement.
1745  *
1746  * This cursor kind is used to describe the jump to "start_over" in the
1747  * goto statement in the following example:
1748  *
1749  * \code
1750  * start_over:
1751  * ++counter;
1752  *
1753  * goto start_over;
1754  * \endcode
1755  *
1756  * A label reference cursor refers to a label statement.
1757  */
1759 
1760  /**
1761  * \brief A reference to a set of overloaded functions or function templates
1762  * that has not yet been resolved to a specific function or function template.
1763  *
1764  * An overloaded declaration reference cursor occurs in C++ templates where
1765  * a dependent name refers to a function. For example:
1766  *
1767  * \code
1768  * template<typename T> void swap(T&, T&);
1769  *
1770  * struct X { ... };
1771  * void swap(X&, X&);
1772  *
1773  * template<typename T>
1774  * void reverse(T* first, T* last) {
1775  * while (first < last - 1) {
1776  * swap(*first, *--last);
1777  * ++first;
1778  * }
1779  * }
1780  *
1781  * struct Y { };
1782  * void swap(Y&, Y&);
1783  * \endcode
1784  *
1785  * Here, the identifier "swap" is associated with an overloaded declaration
1786  * reference. In the template definition, "swap" refers to either of the two
1787  * "swap" functions declared above, so both results will be available. At
1788  * instantiation time, "swap" may also refer to other functions found via
1789  * argument-dependent lookup (e.g., the "swap" function at the end of the
1790  * example).
1791  *
1792  * The functions \c clang_getNumOverloadedDecls() and
1793  * \c clang_getOverloadedDecl() can be used to retrieve the definitions
1794  * referenced by this cursor.
1795  */
1797 
1798  /**
1799  * \brief A reference to a variable that occurs in some non-expression
1800  * context, e.g., a C++ lambda capture list.
1801  */
1803 
1805 
1806  /* Error conditions */
1813 
1814  /* Expressions */
1816 
1817  /**
1818  * \brief An expression whose specific kind is not exposed via this
1819  * interface.
1820  *
1821  * Unexposed expressions have the same operations as any other kind
1822  * of expression; one can extract their location information,
1823  * spelling, children, etc. However, the specific kind of the
1824  * expression is not reported.
1825  */
1827 
1828  /**
1829  * \brief An expression that refers to some value declaration, such
1830  * as a function, variable, or enumerator.
1831  */
1833 
1834  /**
1835  * \brief An expression that refers to a member of a struct, union,
1836  * class, Objective-C class, etc.
1837  */
1839 
1840  /** \brief An expression that calls a function. */
1842 
1843  /** \brief An expression that sends a message to an Objective-C
1844  object or class. */
1846 
1847  /** \brief An expression that represents a block literal. */
1849 
1850  /** \brief An integer literal.
1851  */
1853 
1854  /** \brief A floating point number literal.
1855  */
1857 
1858  /** \brief An imaginary number literal.
1859  */
1861 
1862  /** \brief A string literal.
1863  */
1865 
1866  /** \brief A character literal.
1867  */
1869 
1870  /** \brief A parenthesized expression, e.g. "(1)".
1871  *
1872  * This AST node is only formed if full location information is requested.
1873  */
1875 
1876  /** \brief This represents the unary-expression's (except sizeof and
1877  * alignof).
1878  */
1880 
1881  /** \brief [C99 6.5.2.1] Array Subscripting.
1882  */
1884 
1885  /** \brief A builtin binary operation expression such as "x + y" or
1886  * "x <= y".
1887  */
1889 
1890  /** \brief Compound assignment such as "+=".
1891  */
1893 
1894  /** \brief The ?: ternary operator.
1895  */
1897 
1898  /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++
1899  * (C++ [expr.cast]), which uses the syntax (Type)expr.
1900  *
1901  * For example: (int)f.
1902  */
1904 
1905  /** \brief [C99 6.5.2.5]
1906  */
1908 
1909  /** \brief Describes an C or C++ initializer list.
1910  */
1912 
1913  /** \brief The GNU address of label extension, representing &&label.
1914  */
1916 
1917  /** \brief This is the GNU Statement Expression extension: ({int X=4; X;})
1918  */
1920 
1921  /** \brief Represents a C11 generic selection.
1922  */
1924 
1925  /** \brief Implements the GNU __null extension, which is a name for a null
1926  * pointer constant that has integral type (e.g., int or long) and is the same
1927  * size and alignment as a pointer.
1928  *
1929  * The __null extension is typically only used by system headers, which define
1930  * NULL as __null in C++ rather than using 0 (which is an integer that may not
1931  * match the size of a pointer).
1932  */
1934 
1935  /** \brief C++'s static_cast<> expression.
1936  */
1938 
1939  /** \brief C++'s dynamic_cast<> expression.
1940  */
1942 
1943  /** \brief C++'s reinterpret_cast<> expression.
1944  */
1946 
1947  /** \brief C++'s const_cast<> expression.
1948  */
1950 
1951  /** \brief Represents an explicit C++ type conversion that uses "functional"
1952  * notion (C++ [expr.type.conv]).
1953  *
1954  * Example:
1955  * \code
1956  * x = int(0.5);
1957  * \endcode
1958  */
1960 
1961  /** \brief A C++ typeid expression (C++ [expr.typeid]).
1962  */
1964 
1965  /** \brief [C++ 2.13.5] C++ Boolean Literal.
1966  */
1968 
1969  /** \brief [C++0x 2.14.7] C++ Pointer Literal.
1970  */
1972 
1973  /** \brief Represents the "this" expression in C++
1974  */
1976 
1977  /** \brief [C++ 15] C++ Throw Expression.
1978  *
1979  * This handles 'throw' and 'throw' assignment-expression. When
1980  * assignment-expression isn't present, Op will be null.
1981  */
1983 
1984  /** \brief A new expression for memory allocation and constructor calls, e.g:
1985  * "new CXXNewExpr(foo)".
1986  */
1988 
1989  /** \brief A delete expression for memory deallocation and destructor calls,
1990  * e.g. "delete[] pArray".
1991  */
1993 
1994  /** \brief A unary expression. (noexcept, sizeof, or other traits)
1995  */
1997 
1998  /** \brief An Objective-C string literal i.e. @"foo".
1999  */
2001 
2002  /** \brief An Objective-C \@encode expression.
2003  */
2005 
2006  /** \brief An Objective-C \@selector expression.
2007  */
2009 
2010  /** \brief An Objective-C \@protocol expression.
2011  */
2013 
2014  /** \brief An Objective-C "bridged" cast expression, which casts between
2015  * Objective-C pointers and C pointers, transferring ownership in the process.
2016  *
2017  * \code
2018  * NSString *str = (__bridge_transfer NSString *)CFCreateString();
2019  * \endcode
2020  */
2022 
2023  /** \brief Represents a C++0x pack expansion that produces a sequence of
2024  * expressions.
2025  *
2026  * A pack expansion expression contains a pattern (which itself is an
2027  * expression) followed by an ellipsis. For example:
2028  *
2029  * \code
2030  * template<typename F, typename ...Types>
2031  * void forward(F f, Types &&...args) {
2032  * f(static_cast<Types&&>(args)...);
2033  * }
2034  * \endcode
2035  */
2037 
2038  /** \brief Represents an expression that computes the length of a parameter
2039  * pack.
2040  *
2041  * \code
2042  * template<typename ...Types>
2043  * struct count {
2044  * static const unsigned value = sizeof...(Types);
2045  * };
2046  * \endcode
2047  */
2049 
2050  /* \brief Represents a C++ lambda expression that produces a local function
2051  * object.
2052  *
2053  * \code
2054  * void abssort(float *x, unsigned N) {
2055  * std::sort(x, x + N,
2056  * [](float a, float b) {
2057  * return std::abs(a) < std::abs(b);
2058  * });
2059  * }
2060  * \endcode
2061  */
2063 
2064  /** \brief Objective-c Boolean Literal.
2065  */
2067 
2068  /** \brief Represents the "self" expression in an Objective-C method.
2069  */
2071 
2072  /** \brief OpenMP 4.0 [2.4, Array Section].
2073  */
2075 
2076  /** \brief Represents an @available(...) check.
2077  */
2079 
2081 
2082  /* Statements */
2084  /**
2085  * \brief A statement whose specific kind is not exposed via this
2086  * interface.
2087  *
2088  * Unexposed statements have the same operations as any other kind of
2089  * statement; one can extract their location information, spelling,
2090  * children, etc. However, the specific kind of the statement is not
2091  * reported.
2092  */
2094 
2095  /** \brief A labelled statement in a function.
2096  *
2097  * This cursor kind is used to describe the "start_over:" label statement in
2098  * the following example:
2099  *
2100  * \code
2101  * start_over:
2102  * ++counter;
2103  * \endcode
2104  *
2105  */
2107 
2108  /** \brief A group of statements like { stmt stmt }.
2109  *
2110  * This cursor kind is used to describe compound statements, e.g. function
2111  * bodies.
2112  */
2114 
2115  /** \brief A case statement.
2116  */
2118 
2119  /** \brief A default statement.
2120  */
2122 
2123  /** \brief An if statement
2124  */
2126 
2127  /** \brief A switch statement.
2128  */
2130 
2131  /** \brief A while statement.
2132  */
2134 
2135  /** \brief A do statement.
2136  */
2138 
2139  /** \brief A for statement.
2140  */
2142 
2143  /** \brief A goto statement.
2144  */
2146 
2147  /** \brief An indirect goto statement.
2148  */
2150 
2151  /** \brief A continue statement.
2152  */
2154 
2155  /** \brief A break statement.
2156  */
2158 
2159  /** \brief A return statement.
2160  */
2162 
2163  /** \brief A GCC inline assembly statement extension.
2164  */
2167 
2168  /** \brief Objective-C's overall \@try-\@catch-\@finally statement.
2169  */
2171 
2172  /** \brief Objective-C's \@catch statement.
2173  */
2175 
2176  /** \brief Objective-C's \@finally statement.
2177  */
2179 
2180  /** \brief Objective-C's \@throw statement.
2181  */
2183 
2184  /** \brief Objective-C's \@synchronized statement.
2185  */
2187 
2188  /** \brief Objective-C's autorelease pool statement.
2189  */
2191 
2192  /** \brief Objective-C's collection statement.
2193  */
2195 
2196  /** \brief C++'s catch statement.
2197  */
2199 
2200  /** \brief C++'s try statement.
2201  */
2203 
2204  /** \brief C++'s for (* : *) statement.
2205  */
2207 
2208  /** \brief Windows Structured Exception Handling's try statement.
2209  */
2211 
2212  /** \brief Windows Structured Exception Handling's except statement.
2213  */
2215 
2216  /** \brief Windows Structured Exception Handling's finally statement.
2217  */
2219 
2220  /** \brief A MS inline assembly statement extension.
2221  */
2223 
2224  /** \brief The null statement ";": C99 6.8.3p3.
2225  *
2226  * This cursor kind is used to describe the null statement.
2227  */
2229 
2230  /** \brief Adaptor class for mixing declarations with statements and
2231  * expressions.
2232  */
2234 
2235  /** \brief OpenMP parallel directive.
2236  */
2238 
2239  /** \brief OpenMP SIMD directive.
2240  */
2242 
2243  /** \brief OpenMP for directive.
2244  */
2246 
2247  /** \brief OpenMP sections directive.
2248  */
2250 
2251  /** \brief OpenMP section directive.
2252  */
2254 
2255  /** \brief OpenMP single directive.
2256  */
2258 
2259  /** \brief OpenMP parallel for directive.
2260  */
2262 
2263  /** \brief OpenMP parallel sections directive.
2264  */
2266 
2267  /** \brief OpenMP task directive.
2268  */
2270 
2271  /** \brief OpenMP master directive.
2272  */
2274 
2275  /** \brief OpenMP critical directive.
2276  */
2278 
2279  /** \brief OpenMP taskyield directive.
2280  */
2282 
2283  /** \brief OpenMP barrier directive.
2284  */
2286 
2287  /** \brief OpenMP taskwait directive.
2288  */
2290 
2291  /** \brief OpenMP flush directive.
2292  */
2294 
2295  /** \brief Windows Structured Exception Handling's leave statement.
2296  */
2298 
2299  /** \brief OpenMP ordered directive.
2300  */
2302 
2303  /** \brief OpenMP atomic directive.
2304  */
2306 
2307  /** \brief OpenMP for SIMD directive.
2308  */
2310 
2311  /** \brief OpenMP parallel for SIMD directive.
2312  */
2314 
2315  /** \brief OpenMP target directive.
2316  */
2318 
2319  /** \brief OpenMP teams directive.
2320  */
2322 
2323  /** \brief OpenMP taskgroup directive.
2324  */
2326 
2327  /** \brief OpenMP cancellation point directive.
2328  */
2330 
2331  /** \brief OpenMP cancel directive.
2332  */
2334 
2335  /** \brief OpenMP target data directive.
2336  */
2338 
2339  /** \brief OpenMP taskloop directive.
2340  */
2342 
2343  /** \brief OpenMP taskloop simd directive.
2344  */
2346 
2347  /** \brief OpenMP distribute directive.
2348  */
2350 
2351  /** \brief OpenMP target enter data directive.
2352  */
2354 
2355  /** \brief OpenMP target exit data directive.
2356  */
2358 
2359  /** \brief OpenMP target parallel directive.
2360  */
2362 
2363  /** \brief OpenMP target parallel for directive.
2364  */
2366 
2367  /** \brief OpenMP target update directive.
2368  */
2370 
2371  /** \brief OpenMP distribute parallel for directive.
2372  */
2374 
2375  /** \brief OpenMP distribute parallel for simd directive.
2376  */
2378 
2379  /** \brief OpenMP distribute simd directive.
2380  */
2382 
2383  /** \brief OpenMP target parallel for simd directive.
2384  */
2386 
2387  /** \brief OpenMP target simd directive.
2388  */
2390 
2391  /** \brief OpenMP teams distribute directive.
2392  */
2394 
2395  /** \brief OpenMP teams distribute simd directive.
2396  */
2398 
2399  /** \brief OpenMP teams distribute parallel for simd directive.
2400  */
2402 
2403  /** \brief OpenMP teams distribute parallel for directive.
2404  */
2406 
2407  /** \brief OpenMP target teams directive.
2408  */
2410 
2411  /** \brief OpenMP target teams distribute directive.
2412  */
2414 
2415  /** \brief OpenMP target teams distribute parallel for directive.
2416  */
2418 
2419  /** \brief OpenMP target teams distribute parallel for simd directive.
2420  */
2422 
2423  /** \brief OpenMP target teams distribute simd directive.
2424  */
2426 
2428 
2429  /**
2430  * \brief Cursor that represents the translation unit itself.
2431  *
2432  * The translation unit cursor exists primarily to act as the root
2433  * cursor for traversing the contents of a translation unit.
2434  */
2436 
2437  /* Attributes */
2439  /**
2440  * \brief An attribute whose specific kind is not exposed via this
2441  * interface.
2442  */
2444 
2465 
2466  /* Preprocessing */
2474 
2475  /* Extra Declarations */
2476  /**
2477  * \brief A module import declaration.
2478  */
2481  /**
2482  * \brief A static_assert or _Static_assert node
2483  */
2485  /**
2486  * \brief a friend declaration.
2487  */
2491 
2492  /**
2493  * \brief A code completion overload candidate.
2494  */
2496 };
2497 
2498 /**
2499  * \brief A cursor representing some element in the abstract syntax tree for
2500  * a translation unit.
2501  *
2502  * The cursor abstraction unifies the different kinds of entities in a
2503  * program--declaration, statements, expressions, references to declarations,
2504  * etc.--under a single "cursor" abstraction with a common set of operations.
2505  * Common operation for a cursor include: getting the physical location in
2506  * a source file where the cursor points, getting the name associated with a
2507  * cursor, and retrieving cursors for any child nodes of a particular cursor.
2508  *
2509  * Cursors can be produced in two specific ways.
2510  * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
2511  * from which one can use clang_visitChildren() to explore the rest of the
2512  * translation unit. clang_getCursor() maps from a physical source location
2513  * to the entity that resides at that location, allowing one to map from the
2514  * source code into the AST.
2515  */
2516 typedef struct {
2518  int xdata;
2519  const void *data[3];
2520 } CXCursor;
2521 
2522 /**
2523  * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
2524  *
2525  * @{
2526  */
2527 
2528 /**
2529  * \brief Retrieve the NULL cursor, which represents no entity.
2530  */
2532 
2533 /**
2534  * \brief Retrieve the cursor that represents the given translation unit.
2535  *
2536  * The translation unit cursor can be used to start traversing the
2537  * various declarations within the given translation unit.
2538  */
2540 
2541 /**
2542  * \brief Determine whether two cursors are equivalent.
2543  */
2545 
2546 /**
2547  * \brief Returns non-zero if \p cursor is null.
2548  */
2550 
2551 /**
2552  * \brief Compute a hash value for the given cursor.
2553  */
2555 
2556 /**
2557  * \brief Retrieve the kind of the given cursor.
2558  */
2560 
2561 /**
2562  * \brief Determine whether the given cursor kind represents a declaration.
2563  */
2565 
2566 /**
2567  * \brief Determine whether the given cursor kind represents a simple
2568  * reference.
2569  *
2570  * Note that other kinds of cursors (such as expressions) can also refer to
2571  * other cursors. Use clang_getCursorReferenced() to determine whether a
2572  * particular cursor refers to another entity.
2573  */
2575 
2576 /**
2577  * \brief Determine whether the given cursor kind represents an expression.
2578  */
2580 
2581 /**
2582  * \brief Determine whether the given cursor kind represents a statement.
2583  */
2585 
2586 /**
2587  * \brief Determine whether the given cursor kind represents an attribute.
2588  */
2590 
2591 /**
2592  * \brief Determine whether the given cursor has any attributes.
2593  */
2595 
2596 /**
2597  * \brief Determine whether the given cursor kind represents an invalid
2598  * cursor.
2599  */
2601 
2602 /**
2603  * \brief Determine whether the given cursor kind represents a translation
2604  * unit.
2605  */
2607 
2608 /***
2609  * \brief Determine whether the given cursor represents a preprocessing
2610  * element, such as a preprocessor directive or macro instantiation.
2611  */
2613 
2614 /***
2615  * \brief Determine whether the given cursor represents a currently
2616  * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
2617  */
2619 
2620 /**
2621  * \brief Describe the linkage of the entity referred to by a cursor.
2622  */
2624  /** \brief This value indicates that no linkage information is available
2625  * for a provided CXCursor. */
2627  /**
2628  * \brief This is the linkage for variables, parameters, and so on that
2629  * have automatic storage. This covers normal (non-extern) local variables.
2630  */
2632  /** \brief This is the linkage for static variables and static functions. */
2634  /** \brief This is the linkage for entities with external linkage that live
2635  * in C++ anonymous namespaces.*/
2637  /** \brief This is the linkage for entities with true, external linkage. */
2639 };
2640 
2641 /**
2642  * \brief Determine the linkage of the entity referred to by a given cursor.
2643  */
2645 
2647  /** \brief This value indicates that no visibility information is available
2648  * for a provided CXCursor. */
2650 
2651  /** \brief Symbol not seen by the linker. */
2653  /** \brief Symbol seen by the linker but resolves to a symbol inside this object. */
2655  /** \brief Symbol seen by the linker and acts like a normal symbol. */
2657 };
2658 
2659 /**
2660  * \brief Describe the visibility of the entity referred to by a cursor.
2661  *
2662  * This returns the default visibility if not explicitly specified by
2663  * a visibility attribute. The default visibility may be changed by
2664  * commandline arguments.
2665  *
2666  * \param cursor The cursor to query.
2667  *
2668  * \returns The visibility of the cursor.
2669  */
2671 
2672 /**
2673  * \brief Determine the availability of the entity that this cursor refers to,
2674  * taking the current target platform into account.
2675  *
2676  * \param cursor The cursor to query.
2677  *
2678  * \returns The availability of the cursor.
2679  */
2682 
2683 /**
2684  * Describes the availability of a given entity on a particular platform, e.g.,
2685  * a particular class might only be available on Mac OS 10.7 or newer.
2686  */
2687 typedef struct CXPlatformAvailability {
2688  /**
2689  * \brief A string that describes the platform for which this structure
2690  * provides availability information.
2691  *
2692  * Possible values are "ios" or "macos".
2693  */
2695  /**
2696  * \brief The version number in which this entity was introduced.
2697  */
2699  /**
2700  * \brief The version number in which this entity was deprecated (but is
2701  * still available).
2702  */
2704  /**
2705  * \brief The version number in which this entity was obsoleted, and therefore
2706  * is no longer available.
2707  */
2709  /**
2710  * \brief Whether the entity is unconditionally unavailable on this platform.
2711  */
2713  /**
2714  * \brief An optional message to provide to a user of this API, e.g., to
2715  * suggest replacement APIs.
2716  */
2719 
2720 /**
2721  * \brief Determine the availability of the entity that this cursor refers to
2722  * on any platforms for which availability information is known.
2723  *
2724  * \param cursor The cursor to query.
2725  *
2726  * \param always_deprecated If non-NULL, will be set to indicate whether the
2727  * entity is deprecated on all platforms.
2728  *
2729  * \param deprecated_message If non-NULL, will be set to the message text
2730  * provided along with the unconditional deprecation of this entity. The client
2731  * is responsible for deallocating this string.
2732  *
2733  * \param always_unavailable If non-NULL, will be set to indicate whether the
2734  * entity is unavailable on all platforms.
2735  *
2736  * \param unavailable_message If non-NULL, will be set to the message text
2737  * provided along with the unconditional unavailability of this entity. The
2738  * client is responsible for deallocating this string.
2739  *
2740  * \param availability If non-NULL, an array of CXPlatformAvailability instances
2741  * that will be populated with platform availability information, up to either
2742  * the number of platforms for which availability information is available (as
2743  * returned by this function) or \c availability_size, whichever is smaller.
2744  *
2745  * \param availability_size The number of elements available in the
2746  * \c availability array.
2747  *
2748  * \returns The number of platforms (N) for which availability information is
2749  * available (which is unrelated to \c availability_size).
2750  *
2751  * Note that the client is responsible for calling
2752  * \c clang_disposeCXPlatformAvailability to free each of the
2753  * platform-availability structures returned. There are
2754  * \c min(N, availability_size) such structures.
2755  */
2756 CINDEX_LINKAGE int
2758  int *always_deprecated,
2759  CXString *deprecated_message,
2760  int *always_unavailable,
2761  CXString *unavailable_message,
2762  CXPlatformAvailability *availability,
2763  int availability_size);
2764 
2765 /**
2766  * \brief Free the memory associated with a \c CXPlatformAvailability structure.
2767  */
2768 CINDEX_LINKAGE void
2770 
2771 /**
2772  * \brief Describe the "language" of the entity referred to by a cursor.
2773  */
2779 };
2780 
2781 /**
2782  * \brief Determine the "language" of the entity referred to by a given cursor.
2783  */
2785 
2786 /**
2787  * \brief Returns the translation unit that a cursor originated from.
2788  */
2790 
2791 /**
2792  * \brief A fast container representing a set of CXCursors.
2793  */
2794 typedef struct CXCursorSetImpl *CXCursorSet;
2795 
2796 /**
2797  * \brief Creates an empty CXCursorSet.
2798  */
2799 CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void);
2800 
2801 /**
2802  * \brief Disposes a CXCursorSet and releases its associated memory.
2803  */
2804 CINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset);
2805 
2806 /**
2807  * \brief Queries a CXCursorSet to see if it contains a specific CXCursor.
2808  *
2809  * \returns non-zero if the set contains the specified cursor.
2810 */
2811 CINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset,
2812  CXCursor cursor);
2813 
2814 /**
2815  * \brief Inserts a CXCursor into a CXCursorSet.
2816  *
2817  * \returns zero if the CXCursor was already in the set, and non-zero otherwise.
2818 */
2819 CINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset,
2820  CXCursor cursor);
2821 
2822 /**
2823  * \brief Determine the semantic parent of the given cursor.
2824  *
2825  * The semantic parent of a cursor is the cursor that semantically contains
2826  * the given \p cursor. For many declarations, the lexical and semantic parents
2827  * are equivalent (the lexical parent is returned by
2828  * \c clang_getCursorLexicalParent()). They diverge when declarations or
2829  * definitions are provided out-of-line. For example:
2830  *
2831  * \code
2832  * class C {
2833  * void f();
2834  * };
2835  *
2836  * void C::f() { }
2837  * \endcode
2838  *
2839  * In the out-of-line definition of \c C::f, the semantic parent is
2840  * the class \c C, of which this function is a member. The lexical parent is
2841  * the place where the declaration actually occurs in the source code; in this
2842  * case, the definition occurs in the translation unit. In general, the
2843  * lexical parent for a given entity can change without affecting the semantics
2844  * of the program, and the lexical parent of different declarations of the
2845  * same entity may be different. Changing the semantic parent of a declaration,
2846  * on the other hand, can have a major impact on semantics, and redeclarations
2847  * of a particular entity should all have the same semantic context.
2848  *
2849  * In the example above, both declarations of \c C::f have \c C as their
2850  * semantic context, while the lexical context of the first \c C::f is \c C
2851  * and the lexical context of the second \c C::f is the translation unit.
2852  *
2853  * For global declarations, the semantic parent is the translation unit.
2854  */
2856 
2857 /**
2858  * \brief Determine the lexical parent of the given cursor.
2859  *
2860  * The lexical parent of a cursor is the cursor in which the given \p cursor
2861  * was actually written. For many declarations, the lexical and semantic parents
2862  * are equivalent (the semantic parent is returned by
2863  * \c clang_getCursorSemanticParent()). They diverge when declarations or
2864  * definitions are provided out-of-line. For example:
2865  *
2866  * \code
2867  * class C {
2868  * void f();
2869  * };
2870  *
2871  * void C::f() { }
2872  * \endcode
2873  *
2874  * In the out-of-line definition of \c C::f, the semantic parent is
2875  * the class \c C, of which this function is a member. The lexical parent is
2876  * the place where the declaration actually occurs in the source code; in this
2877  * case, the definition occurs in the translation unit. In general, the
2878  * lexical parent for a given entity can change without affecting the semantics
2879  * of the program, and the lexical parent of different declarations of the
2880  * same entity may be different. Changing the semantic parent of a declaration,
2881  * on the other hand, can have a major impact on semantics, and redeclarations
2882  * of a particular entity should all have the same semantic context.
2883  *
2884  * In the example above, both declarations of \c C::f have \c C as their
2885  * semantic context, while the lexical context of the first \c C::f is \c C
2886  * and the lexical context of the second \c C::f is the translation unit.
2887  *
2888  * For declarations written in the global scope, the lexical parent is
2889  * the translation unit.
2890  */
2892 
2893 /**
2894  * \brief Determine the set of methods that are overridden by the given
2895  * method.
2896  *
2897  * In both Objective-C and C++, a method (aka virtual member function,
2898  * in C++) can override a virtual method in a base class. For
2899  * Objective-C, a method is said to override any method in the class's
2900  * base class, its protocols, or its categories' protocols, that has the same
2901  * selector and is of the same kind (class or instance).
2902  * If no such method exists, the search continues to the class's superclass,
2903  * its protocols, and its categories, and so on. A method from an Objective-C
2904  * implementation is considered to override the same methods as its
2905  * corresponding method in the interface.
2906  *
2907  * For C++, a virtual member function overrides any virtual member
2908  * function with the same signature that occurs in its base
2909  * classes. With multiple inheritance, a virtual member function can
2910  * override several virtual member functions coming from different
2911  * base classes.
2912  *
2913  * In all cases, this function determines the immediate overridden
2914  * method, rather than all of the overridden methods. For example, if
2915  * a method is originally declared in a class A, then overridden in B
2916  * (which in inherits from A) and also in C (which inherited from B),
2917  * then the only overridden method returned from this function when
2918  * invoked on C's method will be B's method. The client may then
2919  * invoke this function again, given the previously-found overridden
2920  * methods, to map out the complete method-override set.
2921  *
2922  * \param cursor A cursor representing an Objective-C or C++
2923  * method. This routine will compute the set of methods that this
2924  * method overrides.
2925  *
2926  * \param overridden A pointer whose pointee will be replaced with a
2927  * pointer to an array of cursors, representing the set of overridden
2928  * methods. If there are no overridden methods, the pointee will be
2929  * set to NULL. The pointee must be freed via a call to
2930  * \c clang_disposeOverriddenCursors().
2931  *
2932  * \param num_overridden A pointer to the number of overridden
2933  * functions, will be set to the number of overridden functions in the
2934  * array pointed to by \p overridden.
2935  */
2937  CXCursor **overridden,
2938  unsigned *num_overridden);
2939 
2940 /**
2941  * \brief Free the set of overridden cursors returned by \c
2942  * clang_getOverriddenCursors().
2943  */
2945 
2946 /**
2947  * \brief Retrieve the file that is included by the given inclusion directive
2948  * cursor.
2949  */
2951 
2952 /**
2953  * @}
2954  */
2955 
2956 /**
2957  * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
2958  *
2959  * Cursors represent a location within the Abstract Syntax Tree (AST). These
2960  * routines help map between cursors and the physical locations where the
2961  * described entities occur in the source code. The mapping is provided in
2962  * both directions, so one can map from source code to the AST and back.
2963  *
2964  * @{
2965  */
2966 
2967 /**
2968  * \brief Map a source location to the cursor that describes the entity at that
2969  * location in the source code.
2970  *
2971  * clang_getCursor() maps an arbitrary source location within a translation
2972  * unit down to the most specific cursor that describes the entity at that
2973  * location. For example, given an expression \c x + y, invoking
2974  * clang_getCursor() with a source location pointing to "x" will return the
2975  * cursor for "x"; similarly for "y". If the cursor points anywhere between
2976  * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
2977  * will return a cursor referring to the "+" expression.
2978  *
2979  * \returns a cursor representing the entity at the given source location, or
2980  * a NULL cursor if no such entity can be found.
2981  */
2983 
2984 /**
2985  * \brief Retrieve the physical location of the source constructor referenced
2986  * by the given cursor.
2987  *
2988  * The location of a declaration is typically the location of the name of that
2989  * declaration, where the name of that declaration would occur if it is
2990  * unnamed, or some keyword that introduces that particular declaration.
2991  * The location of a reference is where that reference occurs within the
2992  * source code.
2993  */
2995 
2996 /**
2997  * \brief Retrieve the physical extent of the source construct referenced by
2998  * the given cursor.
2999  *
3000  * The extent of a cursor starts with the file/line/column pointing at the
3001  * first character within the source construct that the cursor refers to and
3002  * ends with the last character within that source construct. For a
3003  * declaration, the extent covers the declaration itself. For a reference,
3004  * the extent covers the location of the reference (e.g., where the referenced
3005  * entity was actually used).
3006  */
3008 
3009 /**
3010  * @}
3011  */
3012 
3013 /**
3014  * \defgroup CINDEX_TYPES Type information for CXCursors
3015  *
3016  * @{
3017  */
3018 
3019 /**
3020  * \brief Describes the kind of type
3021  */
3023  /**
3024  * \brief Represents an invalid type (e.g., where no type is available).
3025  */
3027 
3028  /**
3029  * \brief A type whose specific kind is not exposed via this
3030  * interface.
3031  */
3033 
3034  /* Builtin types */
3067 
3087 
3088  /**
3089  * \brief Represents a type that was referred to using an elaborated type keyword.
3090  *
3091  * E.g., struct S, or via a qualified name, e.g., N::M::type, or both.
3092  */
3094 
3095  /* OpenCL PipeType. */
3097 
3098  /* OpenCL builtin types. */
3139 };
3140 
3141 /**
3142  * \brief Describes the calling convention of a function type
3143  */
3161 
3164 };
3165 
3166 /**
3167  * \brief The type of an element in the abstract syntax tree.
3168  *
3169  */
3170 typedef struct {
3172  void *data[2];
3173 } CXType;
3174 
3175 /**
3176  * \brief Retrieve the type of a CXCursor (if any).
3177  */
3179 
3180 /**
3181  * \brief Pretty-print the underlying type using the rules of the
3182  * language of the translation unit from which it came.
3183  *
3184  * If the type is invalid, an empty string is returned.
3185  */
3187 
3188 /**
3189  * \brief Retrieve the underlying type of a typedef declaration.
3190  *
3191  * If the cursor does not reference a typedef declaration, an invalid type is
3192  * returned.
3193  */
3195 
3196 /**
3197  * \brief Retrieve the integer type of an enum declaration.
3198  *
3199  * If the cursor does not reference an enum declaration, an invalid type is
3200  * returned.
3201  */
3203 
3204 /**
3205  * \brief Retrieve the integer value of an enum constant declaration as a signed
3206  * long long.
3207  *
3208  * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned.
3209  * Since this is also potentially a valid constant value, the kind of the cursor
3210  * must be verified before calling this function.
3211  */
3213 
3214 /**
3215  * \brief Retrieve the integer value of an enum constant declaration as an unsigned
3216  * long long.
3217  *
3218  * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned.
3219  * Since this is also potentially a valid constant value, the kind of the cursor
3220  * must be verified before calling this function.
3221  */
3223 
3224 /**
3225  * \brief Retrieve the bit width of a bit field declaration as an integer.
3226  *
3227  * If a cursor that is not a bit field declaration is passed in, -1 is returned.
3228  */
3230 
3231 /**
3232  * \brief Retrieve the number of non-variadic arguments associated with a given
3233  * cursor.
3234  *
3235  * The number of arguments can be determined for calls as well as for
3236  * declarations of functions or methods. For other cursors -1 is returned.
3237  */
3239 
3240 /**
3241  * \brief Retrieve the argument cursor of a function or method.
3242  *
3243  * The argument cursor can be determined for calls as well as for declarations
3244  * of functions or methods. For other cursors and for invalid indices, an
3245  * invalid cursor is returned.
3246  */
3248 
3249 /**
3250  * \brief Describes the kind of a template argument.
3251  *
3252  * See the definition of llvm::clang::TemplateArgument::ArgKind for full
3253  * element descriptions.
3254  */
3265  /* Indicates an error case, preventing the kind from being deduced. */
3267 };
3268 
3269 /**
3270  *\brief Returns the number of template args of a function decl representing a
3271  * template specialization.
3272  *
3273  * If the argument cursor cannot be converted into a template function
3274  * declaration, -1 is returned.
3275  *
3276  * For example, for the following declaration and specialization:
3277  * template <typename T, int kInt, bool kBool>
3278  * void foo() { ... }
3279  *
3280  * template <>
3281  * void foo<float, -7, true>();
3282  *
3283  * The value 3 would be returned from this call.
3284  */
3286 
3287 /**
3288  * \brief Retrieve the kind of the I'th template argument of the CXCursor C.
3289  *
3290  * If the argument CXCursor does not represent a FunctionDecl, an invalid
3291  * template argument kind is returned.
3292  *
3293  * For example, for the following declaration and specialization:
3294  * template <typename T, int kInt, bool kBool>
3295  * void foo() { ... }
3296  *
3297  * template <>
3298  * void foo<float, -7, true>();
3299  *
3300  * For I = 0, 1, and 2, Type, Integral, and Integral will be returned,
3301  * respectively.
3302  */
3304  CXCursor C, unsigned I);
3305 
3306 /**
3307  * \brief Retrieve a CXType representing the type of a TemplateArgument of a
3308  * function decl representing a template specialization.
3309  *
3310  * If the argument CXCursor does not represent a FunctionDecl whose I'th
3311  * template argument has a kind of CXTemplateArgKind_Integral, an invalid type
3312  * is returned.
3313  *
3314  * For example, for the following declaration and specialization:
3315  * template <typename T, int kInt, bool kBool>
3316  * void foo() { ... }
3317  *
3318  * template <>
3319  * void foo<float, -7, true>();
3320  *
3321  * If called with I = 0, "float", will be returned.
3322  * Invalid types will be returned for I == 1 or 2.
3323  */
3325  unsigned I);
3326 
3327 /**
3328  * \brief Retrieve the value of an Integral TemplateArgument (of a function
3329  * decl representing a template specialization) as a signed long long.
3330  *
3331  * It is undefined to call this function on a CXCursor that does not represent a
3332  * FunctionDecl or whose I'th template argument is not an integral value.
3333  *
3334  * For example, for the following declaration and specialization:
3335  * template <typename T, int kInt, bool kBool>
3336  * void foo() { ... }
3337  *
3338  * template <>
3339  * void foo<float, -7, true>();
3340  *
3341  * If called with I = 1 or 2, -7 or true will be returned, respectively.
3342  * For I == 0, this function's behavior is undefined.
3343  */
3345  unsigned I);
3346 
3347 /**
3348  * \brief Retrieve the value of an Integral TemplateArgument (of a function
3349  * decl representing a template specialization) as an unsigned long long.
3350  *
3351  * It is undefined to call this function on a CXCursor that does not represent a
3352  * FunctionDecl or whose I'th template argument is not an integral value.
3353  *
3354  * For example, for the following declaration and specialization:
3355  * template <typename T, int kInt, bool kBool>
3356  * void foo() { ... }
3357  *
3358  * template <>
3359  * void foo<float, 2147483649, true>();
3360  *
3361  * If called with I = 1 or 2, 2147483649 or true will be returned, respectively.
3362  * For I == 0, this function's behavior is undefined.
3363  */
3365  CXCursor C, unsigned I);
3366 
3367 /**
3368  * \brief Determine whether two CXTypes represent the same type.
3369  *
3370  * \returns non-zero if the CXTypes represent the same type and
3371  * zero otherwise.
3372  */
3374 
3375 /**
3376  * \brief Return the canonical type for a CXType.
3377  *
3378  * Clang's type system explicitly models typedefs and all the ways
3379  * a specific type can be represented. The canonical type is the underlying
3380  * type with all the "sugar" removed. For example, if 'T' is a typedef
3381  * for 'int', the canonical type for 'T' would be 'int'.
3382  */
3384 
3385 /**
3386  * \brief Determine whether a CXType has the "const" qualifier set,
3387  * without looking through typedefs that may have added "const" at a
3388  * different level.
3389  */
3391 
3392 /**
3393  * \brief Determine whether a CXCursor that is a macro, is
3394  * function like.
3395  */
3397 
3398 /**
3399  * \brief Determine whether a CXCursor that is a macro, is a
3400  * builtin one.
3401  */
3403 
3404 /**
3405  * \brief Determine whether a CXCursor that is a function declaration, is an
3406  * inline declaration.
3407  */
3409 
3410 /**
3411  * \brief Determine whether a CXType has the "volatile" qualifier set,
3412  * without looking through typedefs that may have added "volatile" at
3413  * a different level.
3414  */
3416 
3417 /**
3418  * \brief Determine whether a CXType has the "restrict" qualifier set,
3419  * without looking through typedefs that may have added "restrict" at a
3420  * different level.
3421  */
3423 
3424 /**
3425  * \brief Returns the address space of the given type.
3426  */
3428 
3429 /**
3430  * \brief Returns the typedef name of the given type.
3431  */
3433 
3434 /**
3435  * \brief For pointer types, returns the type of the pointee.
3436  */
3438 
3439 /**
3440  * \brief Return the cursor for the declaration of the given type.
3441  */
3443 
3444 /**
3445  * Returns the Objective-C type encoding for the specified declaration.
3446  */
3448 
3449 /**
3450  * Returns the Objective-C type encoding for the specified CXType.
3451  */
3453 
3454 /**
3455  * \brief Retrieve the spelling of a given CXTypeKind.
3456  */
3458 
3459 /**
3460  * \brief Retrieve the calling convention associated with a function type.
3461  *
3462  * If a non-function type is passed in, CXCallingConv_Invalid is returned.
3463  */
3465 
3466 /**
3467  * \brief Retrieve the return type associated with a function type.
3468  *
3469  * If a non-function type is passed in, an invalid type is returned.
3470  */
3472 
3473 /**
3474  * \brief Retrieve the number of non-variadic parameters associated with a
3475  * function type.
3476  *
3477  * If a non-function type is passed in, -1 is returned.
3478  */
3480 
3481 /**
3482  * \brief Retrieve the type of a parameter of a function type.
3483  *
3484  * If a non-function type is passed in or the function does not have enough
3485  * parameters, an invalid type is returned.
3486  */
3488 
3489 /**
3490  * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise.
3491  */
3493 
3494 /**
3495  * \brief Retrieve the return type associated with a given cursor.
3496  *
3497  * This only returns a valid type if the cursor refers to a function or method.
3498  */
3500 
3501 /**
3502  * \brief Return 1 if the CXType is a POD (plain old data) type, and 0
3503  * otherwise.
3504  */
3506 
3507 /**
3508  * \brief Return the element type of an array, complex, or vector type.
3509  *
3510  * If a type is passed in that is not an array, complex, or vector type,
3511  * an invalid type is returned.
3512  */
3514 
3515 /**
3516  * \brief Return the number of elements of an array or vector type.
3517  *
3518  * If a type is passed in that is not an array or vector type,
3519  * -1 is returned.
3520  */
3522 
3523 /**
3524  * \brief Return the element type of an array type.
3525  *
3526  * If a non-array type is passed in, an invalid type is returned.
3527  */
3529 
3530 /**
3531  * \brief Return the array size of a constant array.
3532  *
3533  * If a non-array type is passed in, -1 is returned.
3534  */
3536 
3537 /**
3538  * \brief Retrieve the type named by the qualified-id.
3539  *
3540  * If a non-elaborated type is passed in, an invalid type is returned.
3541  */
3543 
3544 /**
3545  * \brief Determine if a typedef is 'transparent' tag.
3546  *
3547  * A typedef is considered 'transparent' if it shares a name and spelling
3548  * location with its underlying tag type, as is the case with the NS_ENUM macro.
3549  *
3550  * \returns non-zero if transparent and zero otherwise.
3551  */
3553 
3554 /**
3555  * \brief List the possible error codes for \c clang_Type_getSizeOf,
3556  * \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and
3557  * \c clang_Cursor_getOffsetOf.
3558  *
3559  * A value of this enumeration type can be returned if the target type is not
3560  * a valid argument to sizeof, alignof or offsetof.
3561  */
3563  /**
3564  * \brief Type is of kind CXType_Invalid.
3565  */
3567  /**
3568  * \brief The type is an incomplete Type.
3569  */
3571  /**
3572  * \brief The type is a dependent Type.
3573  */
3575  /**
3576  * \brief The type is not a constant size type.
3577  */
3579  /**
3580  * \brief The Field name is not valid for this record.
3581  */
3583 };
3584 
3585 /**
3586  * \brief Return the alignment of a type in bytes as per C++[expr.alignof]
3587  * standard.
3588  *
3589  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3590  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3591  * is returned.
3592  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3593  * returned.
3594  * If the type declaration is not a constant size type,
3595  * CXTypeLayoutError_NotConstantSize is returned.
3596  */
3598 
3599 /**
3600  * \brief Return the class type of an member pointer type.
3601  *
3602  * If a non-member-pointer type is passed in, an invalid type is returned.
3603  */
3605 
3606 /**
3607  * \brief Return the size of a type in bytes as per C++[expr.sizeof] standard.
3608  *
3609  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3610  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3611  * is returned.
3612  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3613  * returned.
3614  */
3616 
3617 /**
3618  * \brief Return the offset of a field named S in a record of type T in bits
3619  * as it would be returned by __offsetof__ as per C++11[18.2p4]
3620  *
3621  * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid
3622  * is returned.
3623  * If the field's type declaration is an incomplete type,
3624  * CXTypeLayoutError_Incomplete is returned.
3625  * If the field's type declaration is a dependent type,
3626  * CXTypeLayoutError_Dependent is returned.
3627  * If the field's name S is not found,
3628  * CXTypeLayoutError_InvalidFieldName is returned.
3629  */
3630 CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S);
3631 
3632 /**
3633  * \brief Return the offset of the field represented by the Cursor.
3634  *
3635  * If the cursor is not a field declaration, -1 is returned.
3636  * If the cursor semantic parent is not a record field declaration,
3637  * CXTypeLayoutError_Invalid is returned.
3638  * If the field's type declaration is an incomplete type,
3639  * CXTypeLayoutError_Incomplete is returned.
3640  * If the field's type declaration is a dependent type,
3641  * CXTypeLayoutError_Dependent is returned.
3642  * If the field's name S is not found,
3643  * CXTypeLayoutError_InvalidFieldName is returned.
3644  */
3646 
3647 /**
3648  * \brief Determine whether the given cursor represents an anonymous record
3649  * declaration.
3650  */
3652 
3654  /** \brief No ref-qualifier was provided. */
3656  /** \brief An lvalue ref-qualifier was provided (\c &). */
3658  /** \brief An rvalue ref-qualifier was provided (\c &&). */
3660 };
3661 
3662 /**
3663  * \brief Returns the number of template arguments for given template
3664  * specialization, or -1 if type \c T is not a template specialization.
3665  */
3667 
3668 /**
3669  * \brief Returns the type template argument of a template class specialization
3670  * at given index.
3671  *
3672  * This function only returns template type arguments and does not handle
3673  * template template arguments or variadic packs.
3674  */
3676 
3677 /**
3678  * \brief Retrieve the ref-qualifier kind of a function or method.
3679  *
3680  * The ref-qualifier is returned for C++ functions or methods. For other types
3681  * or non-C++ declarations, CXRefQualifier_None is returned.
3682  */
3684 
3685 /**
3686  * \brief Returns non-zero if the cursor specifies a Record member that is a
3687  * bitfield.
3688  */
3690 
3691 /**
3692  * \brief Returns 1 if the base class specified by the cursor with kind
3693  * CX_CXXBaseSpecifier is virtual.
3694  */
3696 
3697 /**
3698  * \brief Represents the C++ access control level to a base class for a
3699  * cursor with kind CX_CXXBaseSpecifier.
3700  */
3706 };
3707 
3708 /**
3709  * \brief Returns the access control level for the referenced object.
3710  *
3711  * If the cursor refers to a C++ declaration, its access control level within its
3712  * parent scope is returned. Otherwise, if the cursor refers to a base specifier or
3713  * access specifier, the specifier itself is returned.
3714  */
3716 
3717 /**
3718  * \brief Represents the storage classes as declared in the source. CX_SC_Invalid
3719  * was added for the case that the passed cursor in not a declaration.
3720  */
3730 };
3731 
3732 /**
3733  * \brief Returns the storage class for a function or variable declaration.
3734  *
3735  * If the passed in Cursor is not a function or variable declaration,
3736  * CX_SC_Invalid is returned else the storage class.
3737  */
3739 
3740 /**
3741  * \brief Determine the number of overloaded declarations referenced by a
3742  * \c CXCursor_OverloadedDeclRef cursor.
3743  *
3744  * \param cursor The cursor whose overloaded declarations are being queried.
3745  *
3746  * \returns The number of overloaded declarations referenced by \c cursor. If it
3747  * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0.
3748  */
3750 
3751 /**
3752  * \brief Retrieve a cursor for one of the overloaded declarations referenced
3753  * by a \c CXCursor_OverloadedDeclRef cursor.
3754  *
3755  * \param cursor The cursor whose overloaded declarations are being queried.
3756  *
3757  * \param index The zero-based index into the set of overloaded declarations in
3758  * the cursor.
3759  *
3760  * \returns A cursor representing the declaration referenced by the given
3761  * \c cursor at the specified \c index. If the cursor does not have an
3762  * associated set of overloaded declarations, or if the index is out of bounds,
3763  * returns \c clang_getNullCursor();
3764  */
3766  unsigned index);
3767 
3768 /**
3769  * @}
3770  */
3771 
3772 /**
3773  * \defgroup CINDEX_ATTRIBUTES Information for attributes
3774  *
3775  * @{
3776  */
3777 
3778 /**
3779  * \brief For cursors representing an iboutletcollection attribute,
3780  * this function returns the collection element type.
3781  *
3782  */
3784 
3785 /**
3786  * @}
3787  */
3788 
3789 /**
3790  * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
3791  *
3792  * These routines provide the ability to traverse the abstract syntax tree
3793  * using cursors.
3794  *
3795  * @{
3796  */
3797 
3798 /**
3799  * \brief Describes how the traversal of the children of a particular
3800  * cursor should proceed after visiting a particular child cursor.
3801  *
3802  * A value of this enumeration type should be returned by each
3803  * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
3804  */
3806  /**
3807  * \brief Terminates the cursor traversal.
3808  */
3810  /**
3811  * \brief Continues the cursor traversal with the next sibling of
3812  * the cursor just visited, without visiting its children.
3813  */
3815  /**
3816  * \brief Recursively traverse the children of this cursor, using
3817  * the same visitor and client data.
3818  */
3820 };
3821 
3822 /**
3823  * \brief Visitor invoked for each cursor found by a traversal.
3824  *
3825  * This visitor function will be invoked for each cursor found by
3826  * clang_visitCursorChildren(). Its first argument is the cursor being
3827  * visited, its second argument is the parent visitor for that cursor,
3828  * and its third argument is the client data provided to
3829  * clang_visitCursorChildren().
3830  *
3831  * The visitor should return one of the \c CXChildVisitResult values
3832  * to direct clang_visitCursorChildren().
3833  */
3835  CXCursor parent,
3836  CXClientData client_data);
3837 
3838 /**
3839  * \brief Visit the children of a particular cursor.
3840  *
3841  * This function visits all the direct children of the given cursor,
3842  * invoking the given \p visitor function with the cursors of each
3843  * visited child. The traversal may be recursive, if the visitor returns
3844  * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
3845  * the visitor returns \c CXChildVisit_Break.
3846  *
3847  * \param parent the cursor whose child may be visited. All kinds of
3848  * cursors can be visited, including invalid cursors (which, by
3849  * definition, have no children).
3850  *
3851  * \param visitor the visitor function that will be invoked for each
3852  * child of \p parent.
3853  *
3854  * \param client_data pointer data supplied by the client, which will
3855  * be passed to the visitor each time it is invoked.
3856  *
3857  * \returns a non-zero value if the traversal was terminated
3858  * prematurely by the visitor returning \c CXChildVisit_Break.
3859  */
3861  CXCursorVisitor visitor,
3862  CXClientData client_data);
3863 #ifdef __has_feature
3864 # if __has_feature(blocks)
3865 /**
3866  * \brief Visitor invoked for each cursor found by a traversal.
3867  *
3868  * This visitor block will be invoked for each cursor found by
3869  * clang_visitChildrenWithBlock(). Its first argument is the cursor being
3870  * visited, its second argument is the parent visitor for that cursor.
3871  *
3872  * The visitor should return one of the \c CXChildVisitResult values
3873  * to direct clang_visitChildrenWithBlock().
3874  */
3875 typedef enum CXChildVisitResult
3876  (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent);
3877 
3878 /**
3879  * Visits the children of a cursor using the specified block. Behaves
3880  * identically to clang_visitChildren() in all other respects.
3881  */
3882 CINDEX_LINKAGE unsigned clang_visitChildrenWithBlock(CXCursor parent,
3883  CXCursorVisitorBlock block);
3884 # endif
3885 #endif
3886 
3887 /**
3888  * @}
3889  */
3890 
3891 /**
3892  * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
3893  *
3894  * These routines provide the ability to determine references within and
3895  * across translation units, by providing the names of the entities referenced
3896  * by cursors, follow reference cursors to the declarations they reference,
3897  * and associate declarations with their definitions.
3898  *
3899  * @{
3900  */
3901 
3902 /**
3903  * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced
3904  * by the given cursor.
3905  *
3906  * A Unified Symbol Resolution (USR) is a string that identifies a particular
3907  * entity (function, class, variable, etc.) within a program. USRs can be
3908  * compared across translation units to determine, e.g., when references in
3909  * one translation refer to an entity defined in another translation unit.
3910  */
3912 
3913 /**
3914  * \brief Construct a USR for a specified Objective-C class.
3915  */
3916 CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
3917 
3918 /**
3919  * \brief Construct a USR for a specified Objective-C category.
3920  */
3922  clang_constructUSR_ObjCCategory(const char *class_name,
3923  const char *category_name);
3924 
3925 /**
3926  * \brief Construct a USR for a specified Objective-C protocol.
3927  */
3929  clang_constructUSR_ObjCProtocol(const char *protocol_name);
3930 
3931 /**
3932  * \brief Construct a USR for a specified Objective-C instance variable and
3933  * the USR for its containing class.
3934  */
3936  CXString classUSR);
3937 
3938 /**
3939  * \brief Construct a USR for a specified Objective-C method and
3940  * the USR for its containing class.
3941  */
3943  unsigned isInstanceMethod,
3944  CXString classUSR);
3945 
3946 /**
3947  * \brief Construct a USR for a specified Objective-C property and the USR
3948  * for its containing class.
3949  */
3951  CXString classUSR);
3952 
3953 /**
3954  * \brief Retrieve a name for the entity referenced by this cursor.
3955  */
3957 
3958 /**
3959  * \brief Retrieve a range for a piece that forms the cursors spelling name.
3960  * Most of the times there is only one range for the complete spelling but for
3961  * Objective-C methods and Objective-C message expressions, there are multiple
3962  * pieces for each selector identifier.
3963  *
3964  * \param pieceIndex the index of the spelling name piece. If this is greater
3965  * than the actual number of pieces, it will return a NULL (invalid) range.
3966  *
3967  * \param options Reserved.
3968  */
3970  unsigned pieceIndex,
3971  unsigned options);
3972 
3973 /**
3974  * \brief Retrieve the display name for the entity referenced by this cursor.
3975  *
3976  * The display name contains extra information that helps identify the cursor,
3977  * such as the parameters of a function or template or the arguments of a
3978  * class template specialization.
3979  */
3981 
3982 /** \brief For a cursor that is a reference, retrieve a cursor representing the
3983  * entity that it references.
3984  *
3985  * Reference cursors refer to other entities in the AST. For example, an
3986  * Objective-C superclass reference cursor refers to an Objective-C class.
3987  * This function produces the cursor for the Objective-C class from the
3988  * cursor for the superclass reference. If the input cursor is a declaration or
3989  * definition, it returns that declaration or definition unchanged.
3990  * Otherwise, returns the NULL cursor.
3991  */
3993 
3994 /**
3995  * \brief For a cursor that is either a reference to or a declaration
3996  * of some entity, retrieve a cursor that describes the definition of
3997  * that entity.
3998  *
3999  * Some entities can be declared multiple times within a translation
4000  * unit, but only one of those declarations can also be a
4001  * definition. For example, given:
4002  *
4003  * \code
4004  * int f(int, int);
4005  * int g(int x, int y) { return f(x, y); }
4006  * int f(int a, int b) { return a + b; }
4007  * int f(int, int);
4008  * \endcode
4009  *
4010  * there are three declarations of the function "f", but only the
4011  * second one is a definition. The clang_getCursorDefinition()
4012  * function will take any cursor pointing to a declaration of "f"
4013  * (the first or fourth lines of the example) or a cursor referenced
4014  * that uses "f" (the call to "f' inside "g") and will return a
4015  * declaration cursor pointing to the definition (the second "f"
4016  * declaration).
4017  *
4018  * If given a cursor for which there is no corresponding definition,
4019  * e.g., because there is no definition of that entity within this
4020  * translation unit, returns a NULL cursor.
4021  */
4023 
4024 /**
4025  * \brief Determine whether the declaration pointed to by this cursor
4026  * is also a definition of that entity.
4027  */
4029 
4030 /**
4031  * \brief Retrieve the canonical cursor corresponding to the given cursor.
4032  *
4033  * In the C family of languages, many kinds of entities can be declared several
4034  * times within a single translation unit. For example, a structure type can
4035  * be forward-declared (possibly multiple times) and later defined:
4036  *
4037  * \code
4038  * struct X;
4039  * struct X;
4040  * struct X {
4041  * int member;
4042  * };
4043  * \endcode
4044  *
4045  * The declarations and the definition of \c X are represented by three
4046  * different cursors, all of which are declarations of the same underlying
4047  * entity. One of these cursor is considered the "canonical" cursor, which
4048  * is effectively the representative for the underlying entity. One can
4049  * determine if two cursors are declarations of the same underlying entity by
4050  * comparing their canonical cursors.
4051  *
4052  * \returns The canonical cursor for the entity referred to by the given cursor.
4053  */
4055 
4056 /**
4057  * \brief If the cursor points to a selector identifier in an Objective-C
4058  * method or message expression, this returns the selector index.
4059  *
4060  * After getting a cursor with #clang_getCursor, this can be called to
4061  * determine if the location points to a selector identifier.
4062  *
4063  * \returns The selector index if the cursor is an Objective-C method or message
4064  * expression and the cursor is pointing to a selector identifier, or -1
4065  * otherwise.
4066  */
4068 
4069 /**
4070  * \brief Given a cursor pointing to a C++ method call or an Objective-C
4071  * message, returns non-zero if the method/message is "dynamic", meaning:
4072  *
4073  * For a C++ method: the call is virtual.
4074  * For an Objective-C message: the receiver is an object instance, not 'super'
4075  * or a specific class.
4076  *
4077  * If the method/message is "static" or the cursor does not point to a
4078  * method/message, it will return zero.
4079  */
4081 
4082 /**
4083  * \brief Given a cursor pointing to an Objective-C message or property
4084  * reference, or C++ method call, returns the CXType of the receiver.
4085  */
4087 
4088 /**
4089  * \brief Property attributes for a \c CXCursor_ObjCPropertyDecl.
4090  */
4091 typedef enum {
4107 
4108 /**
4109  * \brief Given a cursor that represents a property declaration, return the
4110  * associated property attributes. The bits are formed from
4111  * \c CXObjCPropertyAttrKind.
4112  *
4113  * \param reserved Reserved for future use, pass 0.
4114  */
4116  unsigned reserved);
4117 
4118 /**
4119  * \brief 'Qualifiers' written next to the return and parameter types in
4120  * Objective-C method declarations.
4121  */
4122 typedef enum {
4131 
4132 /**
4133  * \brief Given a cursor that represents an Objective-C method or parameter
4134  * declaration, return the associated Objective-C qualifiers for the return
4135  * type or the parameter respectively. The bits are formed from
4136  * CXObjCDeclQualifierKind.
4137  */
4139 
4140 /**
4141  * \brief Given a cursor that represents an Objective-C method or property
4142  * declaration, return non-zero if the declaration was affected by "\@optional".
4143  * Returns zero if the cursor is not such a declaration or it is "\@required".
4144  */
4146 
4147 /**
4148  * \brief Returns non-zero if the given cursor is a variadic function or method.
4149  */
4151 
4152 /**
4153  * \brief Returns non-zero if the given cursor points to a symbol marked with
4154  * external_source_symbol attribute.
4155  *
4156  * \param language If non-NULL, and the attribute is present, will be set to
4157  * the 'language' string from the attribute.
4158  *
4159  * \param definedIn If non-NULL, and the attribute is present, will be set to
4160  * the 'definedIn' string from the attribute.
4161  *
4162  * \param isGenerated If non-NULL, and the attribute is present, will be set to
4163  * non-zero if the 'generated_declaration' is set in the attribute.
4164  */
4166  CXString *language, CXString *definedIn,
4167  unsigned *isGenerated);
4168 
4169 /**
4170  * \brief Given a cursor that represents a declaration, return the associated
4171  * comment's source range. The range may include multiple consecutive comments
4172  * with whitespace in between.
4173  */
4175 
4176 /**
4177  * \brief Given a cursor that represents a declaration, return the associated
4178  * comment text, including comment markers.
4179  */
4181 
4182 /**
4183  * \brief Given a cursor that represents a documentable entity (e.g.,
4184  * declaration), return the associated \\brief paragraph; otherwise return the
4185  * first paragraph.
4186  */
4188 
4189 /**
4190  * @}
4191  */
4192 
4193 /** \defgroup CINDEX_MANGLE Name Mangling API Functions
4194  *
4195  * @{
4196  */
4197 
4198 /**
4199  * \brief Retrieve the CXString representing the mangled name of the cursor.
4200  */
4202 
4203 /**
4204  * \brief Retrieve the CXStrings representing the mangled symbols of the C++
4205  * constructor or destructor at the cursor.
4206  */
4208 
4209 /**
4210  * @}
4211  */
4212 
4213 /**
4214  * \defgroup CINDEX_MODULE Module introspection
4215  *
4216  * The functions in this group provide access to information about modules.
4217  *
4218  * @{
4219  */
4220 
4221 typedef void *CXModule;
4222 
4223 /**
4224  * \brief Given a CXCursor_ModuleImportDecl cursor, return the associated module.
4225  */
4227 
4228 /**
4229  * \brief Given a CXFile header file, return the module that contains it, if one
4230  * exists.
4231  */
4232 CINDEX_LINKAGE CXModule clang_getModuleForFile(CXTranslationUnit, CXFile);
4233 
4234 /**
4235  * \param Module a module object.
4236  *
4237  * \returns the module file where the provided module object came from.
4238  */
4239 CINDEX_LINKAGE CXFile clang_Module_getASTFile(CXModule Module);
4240 
4241 /**
4242  * \param Module a module object.
4243  *
4244  * \returns the parent of a sub-module or NULL if the given module is top-level,
4245  * e.g. for 'std.vector' it will return the 'std' module.
4246  */
4247 CINDEX_LINKAGE CXModule clang_Module_getParent(CXModule Module);
4248 
4249 /**
4250  * \param Module a module object.
4251  *
4252  * \returns the name of the module, e.g. for the 'std.vector' sub-module it
4253  * will return "vector".
4254  */
4256 
4257 /**
4258  * \param Module a module object.
4259  *
4260  * \returns the full name of the module, e.g. "std.vector".
4261  */
4263 
4264 /**
4265  * \param Module a module object.
4266  *
4267  * \returns non-zero if the module is a system one.
4268  */
4269 CINDEX_LINKAGE int clang_Module_isSystem(CXModule Module);
4270 
4271 /**
4272  * \param Module a module object.
4273  *
4274  * \returns the number of top level headers associated with this module.
4275  */
4276 CINDEX_LINKAGE unsigned clang_Module_getNumTopLevelHeaders(CXTranslationUnit,
4277  CXModule Module);
4278 
4279 /**
4280  * \param Module a module object.
4281  *
4282  * \param Index top level header index (zero-based).
4283  *
4284  * \returns the specified top level header associated with the module.
4285  */
4287 CXFile clang_Module_getTopLevelHeader(CXTranslationUnit,
4288  CXModule Module, unsigned Index);
4289 
4290 /**
4291  * @}
4292  */
4293 
4294 /**
4295  * \defgroup CINDEX_CPP C++ AST introspection
4296  *
4297  * The routines in this group provide access information in the ASTs specific
4298  * to C++ language features.
4299  *
4300  * @{
4301  */
4302 
4303 /**
4304  * \brief Determine if a C++ constructor is a converting constructor.
4305  */
4307 
4308 /**
4309  * \brief Determine if a C++ constructor is a copy constructor.
4310  */
4312 
4313 /**
4314  * \brief Determine if a C++ constructor is the default constructor.
4315  */
4317 
4318 /**
4319  * \brief Determine if a C++ constructor is a move constructor.
4320  */
4322 
4323 /**
4324  * \brief Determine if a C++ field is declared 'mutable'.
4325  */
4327 
4328 /**
4329  * \brief Determine if a C++ method is declared '= default'.
4330  */
4332 
4333 /**
4334  * \brief Determine if a C++ member function or member function template is
4335  * pure virtual.
4336  */
4338 
4339 /**
4340  * \brief Determine if a C++ member function or member function template is
4341  * declared 'static'.
4342  */
4344 
4345 /**
4346  * \brief Determine if a C++ member function or member function template is
4347  * explicitly declared 'virtual' or if it overrides a virtual method from
4348  * one of the base classes.
4349  */
4351 
4352 /**
4353  * \brief Determine if a C++ member function or member function template is
4354  * declared 'const'.
4355  */
4357 
4358 /**
4359  * \brief Given a cursor that represents a template, determine
4360  * the cursor kind of the specializations would be generated by instantiating
4361  * the template.
4362  *
4363  * This routine can be used to determine what flavor of function template,
4364  * class template, or class template partial specialization is stored in the
4365  * cursor. For example, it can describe whether a class template cursor is
4366  * declared with "struct", "class" or "union".
4367  *
4368  * \param C The cursor to query. This cursor should represent a template
4369  * declaration.
4370  *
4371  * \returns The cursor kind of the specializations that would be generated
4372  * by instantiating the template \p C. If \p C is not a template, returns
4373  * \c CXCursor_NoDeclFound.
4374  */
4376 
4377 /**
4378  * \brief Given a cursor that may represent a specialization or instantiation
4379  * of a template, retrieve the cursor that represents the template that it
4380  * specializes or from which it was instantiated.
4381  *
4382  * This routine determines the template involved both for explicit
4383  * specializations of templates and for implicit instantiations of the template,
4384  * both of which are referred to as "specializations". For a class template
4385  * specialization (e.g., \c std::vector<bool>), this routine will return
4386  * either the primary template (\c std::vector) or, if the specialization was
4387  * instantiated from a class template partial specialization, the class template
4388  * partial specialization. For a class template partial specialization and a
4389  * function template specialization (including instantiations), this
4390  * this routine will return the specialized template.
4391  *
4392  * For members of a class template (e.g., member functions, member classes, or
4393  * static data members), returns the specialized or instantiated member.
4394  * Although not strictly "templates" in the C++ language, members of class
4395  * templates have the same notions of specializations and instantiations that
4396  * templates do, so this routine treats them similarly.
4397  *
4398  * \param C A cursor that may be a specialization of a template or a member
4399  * of a template.
4400  *
4401  * \returns If the given cursor is a specialization or instantiation of a
4402  * template or a member thereof, the template or member that it specializes or
4403  * from which it was instantiated. Otherwise, returns a NULL cursor.
4404  */
4406 
4407 /**
4408  * \brief Given a cursor that references something else, return the source range
4409  * covering that reference.
4410  *
4411  * \param C A cursor pointing to a member reference, a declaration reference, or
4412  * an operator call.
4413  * \param NameFlags A bitset with three independent flags:
4414  * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and
4415  * CXNameRange_WantSinglePiece.
4416  * \param PieceIndex For contiguous names or when passing the flag
4417  * CXNameRange_WantSinglePiece, only one piece with index 0 is
4418  * available. When the CXNameRange_WantSinglePiece flag is not passed for a
4419  * non-contiguous names, this index can be used to retrieve the individual
4420  * pieces of the name. See also CXNameRange_WantSinglePiece.
4421  *
4422  * \returns The piece of the name pointed to by the given cursor. If there is no
4423  * name, or if the PieceIndex is out-of-range, a null-cursor will be returned.
4424  */
4426  unsigned NameFlags,
4427  unsigned PieceIndex);
4428 
4430  /**
4431  * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the
4432  * range.
4433  */
4435 
4436  /**
4437  * \brief Include the explicit template arguments, e.g. <int> in x.f<int>,
4438  * in the range.
4439  */
4441 
4442  /**
4443  * \brief If the name is non-contiguous, return the full spanning range.
4444  *
4445  * Non-contiguous names occur in Objective-C when a selector with two or more
4446  * parameters is used, or in C++ when using an operator:
4447  * \code
4448  * [object doSomething:here withValue:there]; // Objective-C
4449  * return some_vector[1]; // C++
4450  * \endcode
4451  */
4453 };
4454 
4455 /**
4456  * @}
4457  */
4458 
4459 /**
4460  * \defgroup CINDEX_LEX Token extraction and manipulation
4461  *
4462  * The routines in this group provide access to the tokens within a
4463  * translation unit, along with a semantic mapping of those tokens to
4464  * their corresponding cursors.
4465  *
4466  * @{
4467  */
4468 
4469 /**
4470  * \brief Describes a kind of token.
4471  */
4472 typedef enum CXTokenKind {
4473  /**
4474  * \brief A token that contains some kind of punctuation.
4475  */
4477 
4478  /**
4479  * \brief A language keyword.
4480  */
4482 
4483  /**
4484  * \brief An identifier (that is not a keyword).
4485  */
4487 
4488  /**
4489  * \brief A numeric, string, or character literal.
4490  */
4492 
4493  /**
4494  * \brief A comment.
4495  */
4497 } CXTokenKind;
4498 
4499 /**
4500  * \brief Describes a single preprocessing token.
4501  */
4502 typedef struct {
4503  unsigned int_data[4];
4504  void *ptr_data;
4505 } CXToken;
4506 
4507 /**
4508  * \brief Determine the kind of the given token.
4509  */
4511 
4512 /**
4513  * \brief Determine the spelling of the given token.
4514  *
4515  * The spelling of a token is the textual representation of that token, e.g.,
4516  * the text of an identifier or keyword.
4517  */
4519 
4520 /**
4521  * \brief Retrieve the source location of the given token.
4522  */
4524  CXToken);
4525 
4526 /**
4527  * \brief Retrieve a source range that covers the given token.
4528  */
4530 
4531 /**
4532  * \brief Tokenize the source code described by the given range into raw
4533  * lexical tokens.
4534  *
4535  * \param TU the translation unit whose text is being tokenized.
4536  *
4537  * \param Range the source range in which text should be tokenized. All of the
4538  * tokens produced by tokenization will fall within this source range,
4539  *
4540  * \param Tokens this pointer will be set to point to the array of tokens
4541  * that occur within the given source range. The returned pointer must be
4542  * freed with clang_disposeTokens() before the translation unit is destroyed.
4543  *
4544  * \param NumTokens will be set to the number of tokens in the \c *Tokens
4545  * array.
4546  *
4547  */
4548 CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range,
4549  CXToken **Tokens, unsigned *NumTokens);
4550 
4551 /**
4552  * \brief Annotate the given set of tokens by providing cursors for each token
4553  * that can be mapped to a specific entity within the abstract syntax tree.
4554  *
4555  * This token-annotation routine is equivalent to invoking
4556  * clang_getCursor() for the source locations of each of the
4557  * tokens. The cursors provided are filtered, so that only those
4558  * cursors that have a direct correspondence to the token are
4559  * accepted. For example, given a function call \c f(x),
4560  * clang_getCursor() would provide the following cursors:
4561  *
4562  * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
4563  * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
4564  * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
4565  *
4566  * Only the first and last of these cursors will occur within the
4567  * annotate, since the tokens "f" and "x' directly refer to a function
4568  * and a variable, respectively, but the parentheses are just a small
4569  * part of the full syntax of the function call expression, which is
4570  * not provided as an annotation.
4571  *
4572  * \param TU the translation unit that owns the given tokens.
4573  *
4574  * \param Tokens the set of tokens to annotate.
4575  *
4576  * \param NumTokens the number of tokens in \p Tokens.
4577  *
4578  * \param Cursors an array of \p NumTokens cursors, whose contents will be
4579  * replaced with the cursors corresponding to each token.
4580  */
4581 CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU,
4582  CXToken *Tokens, unsigned NumTokens,
4583  CXCursor *Cursors);
4584 
4585 /**
4586  * \brief Free the given set of tokens.
4587  */
4588 CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU,
4589  CXToken *Tokens, unsigned NumTokens);
4590 
4591 /**
4592  * @}
4593  */
4594 
4595 /**
4596  * \defgroup CINDEX_DEBUG Debugging facilities
4597  *
4598  * These routines are used for testing and debugging, only, and should not
4599  * be relied upon.
4600  *
4601  * @{
4602  */
4603 
4604 /* for debug/testing */
4607  const char **startBuf,
4608  const char **endBuf,
4609  unsigned *startLine,
4610  unsigned *startColumn,
4611  unsigned *endLine,
4612  unsigned *endColumn);
4614 CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data,
4615  unsigned stack_size);
4616 
4617 /**
4618  * @}
4619  */
4620 
4621 /**
4622  * \defgroup CINDEX_CODE_COMPLET Code completion
4623  *
4624  * Code completion involves taking an (incomplete) source file, along with
4625  * knowledge of where the user is actively editing that file, and suggesting
4626  * syntactically- and semantically-valid constructs that the user might want to
4627  * use at that particular point in the source code. These data structures and
4628  * routines provide support for code completion.
4629  *
4630  * @{
4631  */
4632 
4633 /**
4634  * \brief A semantic string that describes a code-completion result.
4635  *
4636  * A semantic string that describes the formatting of a code-completion
4637  * result as a single "template" of text that should be inserted into the
4638  * source buffer when a particular code-completion result is selected.
4639  * Each semantic string is made up of some number of "chunks", each of which
4640  * contains some text along with a description of what that text means, e.g.,
4641  * the name of the entity being referenced, whether the text chunk is part of
4642  * the template, or whether it is a "placeholder" that the user should replace
4643  * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
4644  * description of the different kinds of chunks.
4645  */
4646 typedef void *CXCompletionString;
4647 
4648 /**
4649  * \brief A single result of code completion.
4650  */
4651 typedef struct {
4652  /**
4653  * \brief The kind of entity that this completion refers to.
4654  *
4655  * The cursor kind will be a macro, keyword, or a declaration (one of the
4656  * *Decl cursor kinds), describing the entity that the completion is
4657  * referring to.
4658  *
4659  * \todo In the future, we would like to provide a full cursor, to allow
4660  * the client to extract additional information from declaration.
4661  */
4662  enum CXCursorKind CursorKind;
4663 
4664  /**
4665  * \brief The code-completion string that describes how to insert this
4666  * code-completion result into the editing buffer.
4667  */
4668  CXCompletionString CompletionString;
4670 
4671 /**
4672  * \brief Describes a single piece of text within a code-completion string.
4673  *
4674  * Each "chunk" within a code-completion string (\c CXCompletionString) is
4675  * either a piece of text with a specific "kind" that describes how that text
4676  * should be interpreted by the client or is another completion string.
4677  */
4679  /**
4680  * \brief A code-completion string that describes "optional" text that
4681  * could be a part of the template (but is not required).
4682  *
4683  * The Optional chunk is the only kind of chunk that has a code-completion
4684  * string for its representation, which is accessible via
4685  * \c clang_getCompletionChunkCompletionString(). The code-completion string
4686  * describes an additional part of the template that is completely optional.
4687  * For example, optional chunks can be used to describe the placeholders for
4688  * arguments that match up with defaulted function parameters, e.g. given:
4689  *
4690  * \code
4691  * void f(int x, float y = 3.14, double z = 2.71828);
4692  * \endcode
4693  *
4694  * The code-completion string for this function would contain:
4695  * - a TypedText chunk for "f".
4696  * - a LeftParen chunk for "(".
4697  * - a Placeholder chunk for "int x"
4698  * - an Optional chunk containing the remaining defaulted arguments, e.g.,
4699  * - a Comma chunk for ","
4700  * - a Placeholder chunk for "float y"
4701  * - an Optional chunk containing the last defaulted argument:
4702  * - a Comma chunk for ","
4703  * - a Placeholder chunk for "double z"
4704  * - a RightParen chunk for ")"
4705  *
4706  * There are many ways to handle Optional chunks. Two simple approaches are:
4707  * - Completely ignore optional chunks, in which case the template for the
4708  * function "f" would only include the first parameter ("int x").
4709  * - Fully expand all optional chunks, in which case the template for the
4710  * function "f" would have all of the parameters.
4711  */
4713  /**
4714  * \brief Text that a user would be expected to type to get this
4715  * code-completion result.
4716  *
4717  * There will be exactly one "typed text" chunk in a semantic string, which
4718  * will typically provide the spelling of a keyword or the name of a
4719  * declaration that could be used at the current code point. Clients are
4720  * expected to filter the code-completion results based on the text in this
4721  * chunk.
4722  */
4724  /**
4725  * \brief Text that should be inserted as part of a code-completion result.
4726  *
4727  * A "text" chunk represents text that is part of the template to be
4728  * inserted into user code should this particular code-completion result
4729  * be selected.
4730  */
4732  /**
4733  * \brief Placeholder text that should be replaced by the user.
4734  *
4735  * A "placeholder" chunk marks a place where the user should insert text
4736  * into the code-completion template. For example, placeholders might mark
4737  * the function parameters for a function declaration, to indicate that the
4738  * user should provide arguments for each of those parameters. The actual
4739  * text in a placeholder is a suggestion for the text to display before
4740  * the user replaces the placeholder with real code.
4741  */
4743  /**
4744  * \brief Informative text that should be displayed but never inserted as
4745  * part of the template.
4746  *
4747  * An "informative" chunk contains annotations that can be displayed to
4748  * help the user decide whether a particular code-completion result is the
4749  * right option, but which is not part of the actual template to be inserted
4750  * by code completion.
4751  */
4753  /**
4754  * \brief Text that describes the current parameter when code-completion is
4755  * referring to function call, message send, or template specialization.
4756  *
4757  * A "current parameter" chunk occurs when code-completion is providing
4758  * information about a parameter corresponding to the argument at the
4759  * code-completion point. For example, given a function
4760  *
4761  * \code
4762  * int add(int x, int y);
4763  * \endcode
4764  *
4765  * and the source code \c add(, where the code-completion point is after the
4766  * "(", the code-completion string will contain a "current parameter" chunk
4767  * for "int x", indicating that the current argument will initialize that
4768  * parameter. After typing further, to \c add(17, (where the code-completion
4769  * point is after the ","), the code-completion string will contain a
4770  * "current paremeter" chunk to "int y".
4771  */
4773  /**
4774  * \brief A left parenthesis ('('), used to initiate a function call or
4775  * signal the beginning of a function parameter list.
4776  */
4778  /**
4779  * \brief A right parenthesis (')'), used to finish a function call or
4780  * signal the end of a function parameter list.
4781  */
4783  /**
4784  * \brief A left bracket ('[').
4785  */
4787  /**
4788  * \brief A right bracket (']').
4789  */
4791  /**
4792  * \brief A left brace ('{').
4793  */
4795  /**
4796  * \brief A right brace ('}').
4797  */
4799  /**
4800  * \brief A left angle bracket ('<').
4801  */
4803  /**
4804  * \brief A right angle bracket ('>').
4805  */
4807  /**
4808  * \brief A comma separator (',').
4809  */
4811  /**
4812  * \brief Text that specifies the result type of a given result.
4813  *
4814  * This special kind of informative chunk is not meant to be inserted into
4815  * the text buffer. Rather, it is meant to illustrate the type that an
4816  * expression using the given completion string would have.
4817  */
4819  /**
4820  * \brief A colon (':').
4821  */
4823  /**
4824  * \brief A semicolon (';').
4825  */
4827  /**
4828  * \brief An '=' sign.
4829  */
4831  /**
4832  * Horizontal space (' ').
4833  */
4835  /**
4836  * Vertical space ('\\n'), after which it is generally a good idea to
4837  * perform indentation.
4838  */
4840 };
4841 
4842 /**
4843  * \brief Determine the kind of a particular chunk within a completion string.
4844  *
4845  * \param completion_string the completion string to query.
4846  *
4847  * \param chunk_number the 0-based index of the chunk in the completion string.
4848  *
4849  * \returns the kind of the chunk at the index \c chunk_number.
4850  */
4852 clang_getCompletionChunkKind(CXCompletionString completion_string,
4853  unsigned chunk_number);
4854 
4855 /**
4856  * \brief Retrieve the text associated with a particular chunk within a
4857  * completion string.
4858  *
4859  * \param completion_string the completion string to query.
4860  *
4861  * \param chunk_number the 0-based index of the chunk in the completion string.
4862  *
4863  * \returns the text associated with the chunk at index \c chunk_number.
4864  */
4866 clang_getCompletionChunkText(CXCompletionString completion_string,
4867  unsigned chunk_number);
4868 
4869 /**
4870  * \brief Retrieve the completion string associated with a particular chunk
4871  * within a completion string.
4872  *
4873  * \param completion_string the completion string to query.
4874  *
4875  * \param chunk_number the 0-based index of the chunk in the completion string.
4876  *
4877  * \returns the completion string associated with the chunk at index
4878  * \c chunk_number.
4879  */
4880 CINDEX_LINKAGE CXCompletionString
4881 clang_getCompletionChunkCompletionString(CXCompletionString completion_string,
4882  unsigned chunk_number);
4883 
4884 /**
4885  * \brief Retrieve the number of chunks in the given code-completion string.
4886  */
4887 CINDEX_LINKAGE unsigned
4888 clang_getNumCompletionChunks(CXCompletionString completion_string);
4889 
4890 /**
4891  * \brief Determine the priority of this code completion.
4892  *
4893  * The priority of a code completion indicates how likely it is that this
4894  * particular completion is the completion that the user will select. The
4895  * priority is selected by various internal heuristics.
4896  *
4897  * \param completion_string The completion string to query.
4898  *
4899  * \returns The priority of this completion string. Smaller values indicate
4900  * higher-priority (more likely) completions.
4901  */
4902 CINDEX_LINKAGE unsigned
4903 clang_getCompletionPriority(CXCompletionString completion_string);
4904 
4905 /**
4906  * \brief Determine the availability of the entity that this code-completion
4907  * string refers to.
4908  *
4909  * \param completion_string The completion string to query.
4910  *
4911  * \returns The availability of the completion string.
4912  */
4914 clang_getCompletionAvailability(CXCompletionString completion_string);
4915 
4916 /**
4917  * \brief Retrieve the number of annotations associated with the given
4918  * completion string.
4919  *
4920  * \param completion_string the completion string to query.
4921  *
4922  * \returns the number of annotations associated with the given completion
4923  * string.
4924  */
4925 CINDEX_LINKAGE unsigned
4926 clang_getCompletionNumAnnotations(CXCompletionString completion_string);
4927 
4928 /**
4929  * \brief Retrieve the annotation associated with the given completion string.
4930  *
4931  * \param completion_string the completion string to query.
4932  *
4933  * \param annotation_number the 0-based index of the annotation of the
4934  * completion string.
4935  *
4936  * \returns annotation string associated with the completion at index
4937  * \c annotation_number, or a NULL string if that annotation is not available.
4938  */
4940 clang_getCompletionAnnotation(CXCompletionString completion_string,
4941  unsigned annotation_number);
4942 
4943 /**
4944  * \brief Retrieve the parent context of the given completion string.
4945  *
4946  * The parent context of a completion string is the semantic parent of
4947  * the declaration (if any) that the code completion represents. For example,
4948  * a code completion for an Objective-C method would have the method's class
4949  * or protocol as its context.
4950  *
4951  * \param completion_string The code completion string whose parent is
4952  * being queried.
4953  *
4954  * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL.
4955  *
4956  * \returns The name of the completion parent, e.g., "NSObject" if
4957  * the completion string represents a method in the NSObject class.
4958  */
4960 clang_getCompletionParent(CXCompletionString completion_string,
4961  enum CXCursorKind *kind);
4962 
4963 /**
4964  * \brief Retrieve the brief documentation comment attached to the declaration
4965  * that corresponds to the given completion string.
4966  */
4968 clang_getCompletionBriefComment(CXCompletionString completion_string);
4969 
4970 /**
4971  * \brief Retrieve a completion string for an arbitrary declaration or macro
4972  * definition cursor.
4973  *
4974  * \param cursor The cursor to query.
4975  *
4976  * \returns A non-context-sensitive completion string for declaration and macro
4977  * definition cursors, or NULL for other kinds of cursors.
4978  */
4979 CINDEX_LINKAGE CXCompletionString
4981 
4982 /**
4983  * \brief Contains the results of code-completion.
4984  *
4985  * This data structure contains the results of code completion, as
4986  * produced by \c clang_codeCompleteAt(). Its contents must be freed by
4987  * \c clang_disposeCodeCompleteResults.
4988  */
4989 typedef struct {
4990  /**
4991  * \brief The code-completion results.
4992  */
4994 
4995  /**
4996  * \brief The number of code-completion results stored in the
4997  * \c Results array.
4998  */
4999  unsigned NumResults;
5001 
5002 /**
5003  * \brief Flags that can be passed to \c clang_codeCompleteAt() to
5004  * modify its behavior.
5005  *
5006  * The enumerators in this enumeration can be bitwise-OR'd together to
5007  * provide multiple options to \c clang_codeCompleteAt().
5008  */
5010  /**
5011  * \brief Whether to include macros within the set of code
5012  * completions returned.
5013  */
5015 
5016  /**
5017  * \brief Whether to include code patterns for language constructs
5018  * within the set of code completions, e.g., for loops.
5019  */
5021 
5022  /**
5023  * \brief Whether to include brief documentation within the set of code
5024  * completions returned.
5025  */
5027 };
5028 
5029 /**
5030  * \brief Bits that represent the context under which completion is occurring.
5031  *
5032  * The enumerators in this enumeration may be bitwise-OR'd together if multiple
5033  * contexts are occurring simultaneously.
5034  */
5036  /**
5037  * \brief The context for completions is unexposed, as only Clang results
5038  * should be included. (This is equivalent to having no context bits set.)
5039  */
5041 
5042  /**
5043  * \brief Completions for any possible type should be included in the results.
5044  */
5046 
5047  /**
5048  * \brief Completions for any possible value (variables, function calls, etc.)
5049  * should be included in the results.
5050  */
5052  /**
5053  * \brief Completions for values that resolve to an Objective-C object should
5054  * be included in the results.
5055  */
5057  /**
5058  * \brief Completions for values that resolve to an Objective-C selector
5059  * should be included in the results.
5060  */
5062  /**
5063  * \brief Completions for values that resolve to a C++ class type should be
5064  * included in the results.
5065  */
5067 
5068  /**
5069  * \brief Completions for fields of the member being accessed using the dot
5070  * operator should be included in the results.
5071  */
5073  /**
5074  * \brief Completions for fields of the member being accessed using the arrow
5075  * operator should be included in the results.
5076  */
5078  /**
5079  * \brief Completions for properties of the Objective-C object being accessed
5080  * using the dot operator should be included in the results.
5081  */
5083 
5084  /**
5085  * \brief Completions for enum tags should be included in the results.
5086  */
5088  /**
5089  * \brief Completions for union tags should be included in the results.
5090  */
5092  /**
5093  * \brief Completions for struct tags should be included in the results.
5094  */
5096 
5097  /**
5098  * \brief Completions for C++ class names should be included in the results.
5099  */
5101  /**
5102  * \brief Completions for C++ namespaces and namespace aliases should be
5103  * included in the results.
5104  */
5106  /**
5107  * \brief Completions for C++ nested name specifiers should be included in
5108  * the results.
5109  */
5111 
5112  /**
5113  * \brief Completions for Objective-C interfaces (classes) should be included
5114  * in the results.
5115  */
5117  /**
5118  * \brief Completions for Objective-C protocols should be included in
5119  * the results.
5120  */
5122  /**
5123  * \brief Completions for Objective-C categories should be included in
5124  * the results.
5125  */
5127  /**
5128  * \brief Completions for Objective-C instance messages should be included
5129  * in the results.
5130  */
5132  /**
5133  * \brief Completions for Objective-C class messages should be included in
5134  * the results.
5135  */
5137  /**
5138  * \brief Completions for Objective-C selector names should be included in
5139  * the results.
5140  */
5142 
5143  /**
5144  * \brief Completions for preprocessor macro names should be included in
5145  * the results.
5146  */
5148 
5149  /**
5150  * \brief Natural language completions should be included in the results.
5151  */
5153 
5154  /**
5155  * \brief The current context is unknown, so set all contexts.
5156  */
5158 };
5159 
5160 /**
5161  * \brief Returns a default set of code-completion options that can be
5162  * passed to\c clang_codeCompleteAt().
5163  */
5165 
5166 /**
5167  * \brief Perform code completion at a given location in a translation unit.
5168  *
5169  * This function performs code completion at a particular file, line, and
5170  * column within source code, providing results that suggest potential
5171  * code snippets based on the context of the completion. The basic model
5172  * for code completion is that Clang will parse a complete source file,
5173  * performing syntax checking up to the location where code-completion has
5174  * been requested. At that point, a special code-completion token is passed
5175  * to the parser, which recognizes this token and determines, based on the
5176  * current location in the C/Objective-C/C++ grammar and the state of
5177  * semantic analysis, what completions to provide. These completions are
5178  * returned via a new \c CXCodeCompleteResults structure.
5179  *
5180  * Code completion itself is meant to be triggered by the client when the
5181  * user types punctuation characters or whitespace, at which point the
5182  * code-completion location will coincide with the cursor. For example, if \c p
5183  * is a pointer, code-completion might be triggered after the "-" and then
5184  * after the ">" in \c p->. When the code-completion location is afer the ">",
5185  * the completion results will provide, e.g., the members of the struct that
5186  * "p" points to. The client is responsible for placing the cursor at the
5187  * beginning of the token currently being typed, then filtering the results
5188  * based on the contents of the token. For example, when code-completing for
5189  * the expression \c p->get, the client should provide the location just after
5190  * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
5191  * client can filter the results based on the current token text ("get"), only
5192  * showing those results that start with "get". The intent of this interface
5193  * is to separate the relatively high-latency acquisition of code-completion
5194  * results from the filtering of results on a per-character basis, which must
5195  * have a lower latency.
5196  *
5197  * \param TU The translation unit in which code-completion should
5198  * occur. The source files for this translation unit need not be
5199  * completely up-to-date (and the contents of those source files may
5200  * be overridden via \p unsaved_files). Cursors referring into the
5201  * translation unit may be invalidated by this invocation.
5202  *
5203  * \param complete_filename The name of the source file where code
5204  * completion should be performed. This filename may be any file
5205  * included in the translation unit.
5206  *
5207  * \param complete_line The line at which code-completion should occur.
5208  *
5209  * \param complete_column The column at which code-completion should occur.
5210  * Note that the column should point just after the syntactic construct that
5211  * initiated code completion, and not in the middle of a lexical token.
5212  *
5213  * \param unsaved_files the Files that have not yet been saved to disk
5214  * but may be required for parsing or code completion, including the
5215  * contents of those files. The contents and name of these files (as
5216  * specified by CXUnsavedFile) are copied when necessary, so the
5217  * client only needs to guarantee their validity until the call to
5218  * this function returns.
5219  *
5220  * \param num_unsaved_files The number of unsaved file entries in \p
5221  * unsaved_files.
5222  *
5223  * \param options Extra options that control the behavior of code
5224  * completion, expressed as a bitwise OR of the enumerators of the
5225  * CXCodeComplete_Flags enumeration. The
5226  * \c clang_defaultCodeCompleteOptions() function returns a default set
5227  * of code-completion options.
5228  *
5229  * \returns If successful, a new \c CXCodeCompleteResults structure
5230  * containing code-completion results, which should eventually be
5231  * freed with \c clang_disposeCodeCompleteResults(). If code
5232  * completion fails, returns NULL.
5233  */
5235 CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU,
5236  const char *complete_filename,
5237  unsigned complete_line,
5238  unsigned complete_column,
5239  struct CXUnsavedFile *unsaved_files,
5240  unsigned num_unsaved_files,
5241  unsigned options);
5242 
5243 /**
5244  * \brief Sort the code-completion results in case-insensitive alphabetical
5245  * order.
5246  *
5247  * \param Results The set of results to sort.
5248  * \param NumResults The number of results in \p Results.
5249  */
5252  unsigned NumResults);
5253 
5254 /**
5255  * \brief Free the given set of code-completion results.
5256  */
5259 
5260 /**
5261  * \brief Determine the number of diagnostics produced prior to the
5262  * location where code completion was performed.
5263  */
5266 
5267 /**
5268  * \brief Retrieve a diagnostic associated with the given code completion.
5269  *
5270  * \param Results the code completion results to query.
5271  * \param Index the zero-based diagnostic number to retrieve.
5272  *
5273  * \returns the requested diagnostic. This diagnostic must be freed
5274  * via a call to \c clang_disposeDiagnostic().
5275  */
5278  unsigned Index);
5279 
5280 /**
5281  * \brief Determines what completions are appropriate for the context
5282  * the given code completion.
5283  *
5284  * \param Results the code completion results to query
5285  *
5286  * \returns the kinds of completions that are appropriate for use
5287  * along with the given code completion results.
5288  */
5290 unsigned long long clang_codeCompleteGetContexts(
5291  CXCodeCompleteResults *Results);
5292 
5293 /**
5294  * \brief Returns the cursor kind for the container for the current code
5295  * completion context. The container is only guaranteed to be set for
5296  * contexts where a container exists (i.e. member accesses or Objective-C
5297  * message sends); if there is not a container, this function will return
5298  * CXCursor_InvalidCode.
5299  *
5300  * \param Results the code completion results to query
5301  *
5302  * \param IsIncomplete on return, this value will be false if Clang has complete
5303  * information about the container. If Clang does not have complete
5304  * information, this value will be true.
5305  *
5306  * \returns the container kind, or CXCursor_InvalidCode if there is not a
5307  * container
5308  */
5311  CXCodeCompleteResults *Results,
5312  unsigned *IsIncomplete);
5313 
5314 /**
5315  * \brief Returns the USR for the container for the current code completion
5316  * context. If there is not a container for the current context, this
5317  * function will return the empty string.
5318  *
5319  * \param Results the code completion results to query
5320  *
5321  * \returns the USR for the container
5322  */
5325 
5326 /**
5327  * \brief Returns the currently-entered selector for an Objective-C message
5328  * send, formatted like "initWithFoo:bar:". Only guaranteed to return a
5329  * non-empty string for CXCompletionContext_ObjCInstanceMessage and
5330  * CXCompletionContext_ObjCClassMessage.
5331  *
5332  * \param Results the code completion results to query
5333  *
5334  * \returns the selector (or partial selector) that has been entered thus far
5335  * for an Objective-C message send.
5336  */
5339 
5340 /**
5341  * @}
5342  */
5343 
5344 /**
5345  * \defgroup CINDEX_MISC Miscellaneous utility functions
5346  *
5347  * @{
5348  */
5349 
5350 /**
5351  * \brief Return a version string, suitable for showing to a user, but not
5352  * intended to be parsed (the format is not guaranteed to be stable).
5353  */
5355 
5356 /**
5357  * \brief Enable/disable crash recovery.
5358  *
5359  * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero
5360  * value enables crash recovery, while 0 disables it.
5361  */
5363 
5364  /**
5365  * \brief Visitor invoked for each file in a translation unit
5366  * (used with clang_getInclusions()).
5367  *
5368  * This visitor function will be invoked by clang_getInclusions() for each
5369  * file included (either at the top-level or by \#include directives) within
5370  * a translation unit. The first argument is the file being included, and
5371  * the second and third arguments provide the inclusion stack. The
5372  * array is sorted in order of immediate inclusion. For example,
5373  * the first element refers to the location that included 'included_file'.
5374  */
5375 typedef void (*CXInclusionVisitor)(CXFile included_file,
5376  CXSourceLocation* inclusion_stack,
5377  unsigned include_len,
5378  CXClientData client_data);
5379 
5380 /**
5381  * \brief Visit the set of preprocessor inclusions in a translation unit.
5382  * The visitor function is called with the provided data for every included
5383  * file. This does not include headers included by the PCH file (unless one
5384  * is inspecting the inclusions in the PCH file itself).
5385  */
5386 CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu,
5387  CXInclusionVisitor visitor,
5388  CXClientData client_data);
5389 
5390 typedef enum {
5397 
5399 
5400 } CXEvalResultKind ;
5401 
5402 /**
5403  * \brief Evaluation result of a cursor
5404  */
5405 typedef void * CXEvalResult;
5406 
5407 /**
5408  * \brief If cursor is a statement declaration tries to evaluate the
5409  * statement and if its variable, tries to evaluate its initializer,
5410  * into its corresponding type.
5411  */
5413 
5414 /**
5415  * \brief Returns the kind of the evaluated result.
5416  */
5418 
5419 /**
5420  * \brief Returns the evaluation result as integer if the
5421  * kind is Int.
5422  */
5423 CINDEX_LINKAGE int clang_EvalResult_getAsInt(CXEvalResult E);
5424 
5425 /**
5426  * \brief Returns the evaluation result as a long long integer if the
5427  * kind is Int. This prevents overflows that may happen if the result is
5428  * returned with clang_EvalResult_getAsInt.
5429  */
5430 CINDEX_LINKAGE long long clang_EvalResult_getAsLongLong(CXEvalResult E);
5431 
5432 /**
5433  * \brief Returns a non-zero value if the kind is Int and the evaluation
5434  * result resulted in an unsigned integer.
5435  */
5436 CINDEX_LINKAGE unsigned clang_EvalResult_isUnsignedInt(CXEvalResult E);
5437 
5438 /**
5439  * \brief Returns the evaluation result as an unsigned integer if
5440  * the kind is Int and clang_EvalResult_isUnsignedInt is non-zero.
5441  */
5442 CINDEX_LINKAGE unsigned long long clang_EvalResult_getAsUnsigned(CXEvalResult E);
5443 
5444 /**
5445  * \brief Returns the evaluation result as double if the
5446  * kind is double.
5447  */
5448 CINDEX_LINKAGE double clang_EvalResult_getAsDouble(CXEvalResult E);
5449 
5450 /**
5451  * \brief Returns the evaluation result as a constant string if the
5452  * kind is other than Int or float. User must not free this pointer,
5453  * instead call clang_EvalResult_dispose on the CXEvalResult returned
5454  * by clang_Cursor_Evaluate.
5455  */
5456 CINDEX_LINKAGE const char* clang_EvalResult_getAsStr(CXEvalResult E);
5457 
5458 /**
5459  * \brief Disposes the created Eval memory.
5460  */
5461 CINDEX_LINKAGE void clang_EvalResult_dispose(CXEvalResult E);
5462 /**
5463  * @}
5464  */
5465 
5466 /** \defgroup CINDEX_REMAPPING Remapping functions
5467  *
5468  * @{
5469  */
5470 
5471 /**
5472  * \brief A remapping of original source files and their translated files.
5473  */
5474 typedef void *CXRemapping;
5475 
5476 /**
5477  * \brief Retrieve a remapping.
5478  *
5479  * \param path the path that contains metadata about remappings.
5480  *
5481  * \returns the requested remapping. This remapping must be freed
5482  * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred.
5483  */
5484 CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path);
5485 
5486 /**
5487  * \brief Retrieve a remapping.
5488  *
5489  * \param filePaths pointer to an array of file paths containing remapping info.
5490  *
5491  * \param numFiles number of file paths.
5492  *
5493  * \returns the requested remapping. This remapping must be freed
5494  * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred.
5495  */
5497 CXRemapping clang_getRemappingsFromFileList(const char **filePaths,
5498  unsigned numFiles);
5499 
5500 /**
5501  * \brief Determine the number of remappings.
5502  */
5503 CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping);
5504 
5505 /**
5506  * \brief Get the original and the associated filename from the remapping.
5507  *
5508  * \param original If non-NULL, will be set to the original filename.
5509  *
5510  * \param transformed If non-NULL, will be set to the filename that the original
5511  * is associated with.
5512  */
5513 CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index,
5514  CXString *original, CXString *transformed);
5515 
5516 /**
5517  * \brief Dispose the remapping.
5518  */
5519 CINDEX_LINKAGE void clang_remap_dispose(CXRemapping);
5520 
5521 /**
5522  * @}
5523  */
5524 
5525 /** \defgroup CINDEX_HIGH Higher level API functions
5526  *
5527  * @{
5528  */
5529 
5533 };
5534 
5535 typedef struct CXCursorAndRangeVisitor {
5536  void *context;
5537  enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange);
5539 
5540 typedef enum {
5541  /**
5542  * \brief Function returned successfully.
5543  */
5545  /**
5546  * \brief One of the parameters was invalid for the function.
5547  */
5549  /**
5550  * \brief The function was terminated by a callback (e.g. it returned
5551  * CXVisit_Break)
5552  */
5554 
5555 } CXResult;
5556 
5557 /**
5558  * \brief Find references of a declaration in a specific file.
5559  *
5560  * \param cursor pointing to a declaration or a reference of one.
5561  *
5562  * \param file to search for references.
5563  *
5564  * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for
5565  * each reference found.
5566  * The CXSourceRange will point inside the file; if the reference is inside
5567  * a macro (and not a macro argument) the CXSourceRange will be invalid.
5568  *
5569  * \returns one of the CXResult enumerators.
5570  */
5572  CXCursorAndRangeVisitor visitor);
5573 
5574 /**
5575  * \brief Find #import/#include directives in a specific file.
5576  *
5577  * \param TU translation unit containing the file to query.
5578  *
5579  * \param file to search for #import/#include directives.
5580  *
5581  * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for
5582  * each directive found.
5583  *
5584  * \returns one of the CXResult enumerators.
5585  */
5586 CINDEX_LINKAGE CXResult clang_findIncludesInFile(CXTranslationUnit TU,
5587  CXFile file,
5588  CXCursorAndRangeVisitor visitor);
5589 
5590 #ifdef __has_feature
5591 # if __has_feature(blocks)
5592 
5593 typedef enum CXVisitorResult
5594  (^CXCursorAndRangeVisitorBlock)(CXCursor, CXSourceRange);
5595 
5597 CXResult clang_findReferencesInFileWithBlock(CXCursor, CXFile,
5598  CXCursorAndRangeVisitorBlock);
5599 
5601 CXResult clang_findIncludesInFileWithBlock(CXTranslationUnit, CXFile,
5602  CXCursorAndRangeVisitorBlock);
5603 
5604 # endif
5605 #endif
5606 
5607 /**
5608  * \brief The client's data object that is associated with a CXFile.
5609  */
5610 typedef void *CXIdxClientFile;
5611 
5612 /**
5613  * \brief The client's data object that is associated with a semantic entity.
5614  */
5615 typedef void *CXIdxClientEntity;
5616 
5617 /**
5618  * \brief The client's data object that is associated with a semantic container
5619  * of entities.
5620  */
5621 typedef void *CXIdxClientContainer;
5622 
5623 /**
5624  * \brief The client's data object that is associated with an AST file (PCH
5625  * or module).
5626  */
5627 typedef void *CXIdxClientASTFile;
5628 
5629 /**
5630  * \brief Source location passed to index callbacks.
5631  */
5632 typedef struct {
5633  void *ptr_data[2];
5634  unsigned int_data;
5635 } CXIdxLoc;
5636 
5637 /**
5638  * \brief Data for ppIncludedFile callback.
5639  */
5640 typedef struct {
5641  /**
5642  * \brief Location of '#' in the \#include/\#import directive.
5643  */
5645  /**
5646  * \brief Filename as written in the \#include/\#import directive.
5647  */
5648  const char *filename;
5649  /**
5650  * \brief The actual file that the \#include/\#import directive resolved to.
5651  */
5652  CXFile file;
5655  /**
5656  * \brief Non-zero if the directive was automatically turned into a module
5657  * import.
5658  */
5661 
5662 /**
5663  * \brief Data for IndexerCallbacks#importedASTFile.
5664  */
5665 typedef struct {
5666  /**
5667  * \brief Top level AST file containing the imported PCH, module or submodule.
5668  */
5669  CXFile file;
5670  /**
5671  * \brief The imported module or NULL if the AST file is a PCH.
5672  */
5673  CXModule module;
5674  /**
5675  * \brief Location where the file is imported. Applicable only for modules.
5676  */
5678  /**
5679  * \brief Non-zero if an inclusion directive was automatically turned into
5680  * a module import. Applicable only for modules.
5681  */
5683 
5685 
5686 typedef enum {
5693 
5697 
5702 
5706