clang  16.0.0git
Index.h
Go to the documentation of this file.
1 /*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\
2 |* *|
3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
4 |* Exceptions. *|
5 |* See https://llvm.org/LICENSE.txt for license information. *|
6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
7 |* *|
8 |*===----------------------------------------------------------------------===*|
9 |* *|
10 |* This header provides a public interface to a Clang library for extracting *|
11 |* high-level symbol information from source files without exposing the full *|
12 |* Clang C++ API. *|
13 |* *|
14 \*===----------------------------------------------------------------------===*/
15 
16 #ifndef LLVM_CLANG_C_INDEX_H
17 #define LLVM_CLANG_C_INDEX_H
18 
19 #include "clang-c/BuildSystem.h"
20 #include "clang-c/CXDiagnostic.h"
21 #include "clang-c/CXErrorCode.h"
22 #include "clang-c/CXFile.h"
24 #include "clang-c/CXString.h"
25 #include "clang-c/ExternC.h"
26 #include "clang-c/Platform.h"
27 
28 /**
29  * The version constants for the libclang API.
30  * CINDEX_VERSION_MINOR should increase when there are API additions.
31  * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes.
32  *
33  * The policy about the libclang API was always to keep it source and ABI
34  * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable.
35  */
36 #define CINDEX_VERSION_MAJOR 0
37 #define CINDEX_VERSION_MINOR 62
38 
39 #define CINDEX_VERSION_ENCODE(major, minor) (((major)*10000) + ((minor)*1))
40 
41 #define CINDEX_VERSION \
42  CINDEX_VERSION_ENCODE(CINDEX_VERSION_MAJOR, CINDEX_VERSION_MINOR)
43 
44 #define CINDEX_VERSION_STRINGIZE_(major, minor) #major "." #minor
45 #define CINDEX_VERSION_STRINGIZE(major, minor) \
46  CINDEX_VERSION_STRINGIZE_(major, minor)
47 
48 #define CINDEX_VERSION_STRING \
49  CINDEX_VERSION_STRINGIZE(CINDEX_VERSION_MAJOR, CINDEX_VERSION_MINOR)
50 
52 
53 /** \defgroup CINDEX libclang: C Interface to Clang
54  *
55  * The C Interface to Clang provides a relatively small API that exposes
56  * facilities for parsing source code into an abstract syntax tree (AST),
57  * loading already-parsed ASTs, traversing the AST, associating
58  * physical source locations with elements within the AST, and other
59  * facilities that support Clang-based development tools.
60  *
61  * This C interface to Clang will never provide all of the information
62  * representation stored in Clang's C++ AST, nor should it: the intent is to
63  * maintain an API that is relatively stable from one release to the next,
64  * providing only the basic functionality needed to support development tools.
65  *
66  * To avoid namespace pollution, data types are prefixed with "CX" and
67  * functions are prefixed with "clang_".
68  *
69  * @{
70  */
71 
72 /**
73  * An "index" that consists of a set of translation units that would
74  * typically be linked together into an executable or library.
75  */
76 typedef void *CXIndex;
77 
78 /**
79  * An opaque type representing target information for a given translation
80  * unit.
81  */
82 typedef struct CXTargetInfoImpl *CXTargetInfo;
83 
84 /**
85  * A single translation unit, which resides in an index.
86  */
87 typedef struct CXTranslationUnitImpl *CXTranslationUnit;
88 
89 /**
90  * Opaque pointer representing client data that will be passed through
91  * to various callbacks and visitors.
92  */
93 typedef void *CXClientData;
94 
95 /**
96  * Provides the contents of a file that has not yet been saved to disk.
97  *
98  * Each CXUnsavedFile instance provides the name of a file on the
99  * system along with the current contents of that file that have not
100  * yet been saved to disk.
101  */
103  /**
104  * The file whose contents have not yet been saved.
105  *
106  * This file must already exist in the file system.
107  */
108  const char *Filename;
109 
110  /**
111  * A buffer containing the unsaved contents of this file.
112  */
113  const char *Contents;
114 
115  /**
116  * The length of the unsaved contents of this buffer.
117  */
118  unsigned long Length;
119 };
120 
121 /**
122  * Describes the availability of a particular entity, which indicates
123  * whether the use of this entity will result in a warning or error due to
124  * it being deprecated or unavailable.
125  */
127  /**
128  * The entity is available.
129  */
131  /**
132  * The entity is available, but has been deprecated (and its use is
133  * not recommended).
134  */
136  /**
137  * The entity is not available; any use of it will be an error.
138  */
140  /**
141  * The entity is available, but not accessible; any use of it will be
142  * an error.
143  */
145 };
146 
147 /**
148  * Describes a version number of the form major.minor.subminor.
149  */
150 typedef struct CXVersion {
151  /**
152  * The major version number, e.g., the '10' in '10.7.3'. A negative
153  * value indicates that there is no version number at all.
154  */
155  int Major;
156  /**
157  * The minor version number, e.g., the '7' in '10.7.3'. This value
158  * will be negative if no minor version number was provided, e.g., for
159  * version '10'.
160  */
161  int Minor;
162  /**
163  * The subminor version number, e.g., the '3' in '10.7.3'. This value
164  * will be negative if no minor or subminor version number was provided,
165  * e.g., in version '10' or '10.7'.
166  */
167  int Subminor;
168 } CXVersion;
169 
170 /**
171  * Describes the exception specification of a cursor.
172  *
173  * A negative value indicates that the cursor is not a function declaration.
174  */
176  /**
177  * The cursor has no exception specification.
178  */
180 
181  /**
182  * The cursor has exception specification throw()
183  */
185 
186  /**
187  * The cursor has exception specification throw(T1, T2)
188  */
190 
191  /**
192  * The cursor has exception specification throw(...).
193  */
195 
196  /**
197  * The cursor has exception specification basic noexcept.
198  */
200 
201  /**
202  * The cursor has exception specification computed noexcept.
203  */
205 
206  /**
207  * The exception specification has not yet been evaluated.
208  */
210 
211  /**
212  * The exception specification has not yet been instantiated.
213  */
215 
216  /**
217  * The exception specification has not been parsed yet.
218  */
220 
221  /**
222  * The cursor has a __declspec(nothrow) exception specification.
223  */
225 };
226 
227 /**
228  * Provides a shared context for creating translation units.
229  *
230  * It provides two options:
231  *
232  * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local"
233  * declarations (when loading any new translation units). A "local" declaration
234  * is one that belongs in the translation unit itself and not in a precompiled
235  * header that was used by the translation unit. If zero, all declarations
236  * will be enumerated.
237  *
238  * Here is an example:
239  *
240  * \code
241  * // excludeDeclsFromPCH = 1, displayDiagnostics=1
242  * Idx = clang_createIndex(1, 1);
243  *
244  * // IndexTest.pch was produced with the following command:
245  * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch"
246  * TU = clang_createTranslationUnit(Idx, "IndexTest.pch");
247  *
248  * // This will load all the symbols from 'IndexTest.pch'
249  * clang_visitChildren(clang_getTranslationUnitCursor(TU),
250  * TranslationUnitVisitor, 0);
251  * clang_disposeTranslationUnit(TU);
252  *
253  * // This will load all the symbols from 'IndexTest.c', excluding symbols
254  * // from 'IndexTest.pch'.
255  * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" };
256  * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args,
257  * 0, 0);
258  * clang_visitChildren(clang_getTranslationUnitCursor(TU),
259  * TranslationUnitVisitor, 0);
260  * clang_disposeTranslationUnit(TU);
261  * \endcode
262  *
263  * This process of creating the 'pch', loading it separately, and using it (via
264  * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks
265  * (which gives the indexer the same performance benefit as the compiler).
266  */
267 CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH,
268  int displayDiagnostics);
269 
270 /**
271  * Destroy the given index.
272  *
273  * The index must not be destroyed until all of the translation units created
274  * within that index have been destroyed.
275  */
277 
278 typedef enum {
279  /**
280  * Used to indicate that no special CXIndex options are needed.
281  */
283 
284  /**
285  * Used to indicate that threads that libclang creates for indexing
286  * purposes should use background priority.
287  *
288  * Affects #clang_indexSourceFile, #clang_indexTranslationUnit,
289  * #clang_parseTranslationUnit, #clang_saveTranslationUnit.
290  */
292 
293  /**
294  * Used to indicate that threads that libclang creates for editing
295  * purposes should use background priority.
296  *
297  * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt,
298  * #clang_annotateTokens
299  */
301 
302  /**
303  * Used to indicate that all threads that libclang creates should use
304  * background priority.
305  */
309 
311 
312 /**
313  * Sets general options associated with a CXIndex.
314  *
315  * For example:
316  * \code
317  * CXIndex idx = ...;
318  * clang_CXIndex_setGlobalOptions(idx,
319  * clang_CXIndex_getGlobalOptions(idx) |
320  * CXGlobalOpt_ThreadBackgroundPriorityForIndexing);
321  * \endcode
322  *
323  * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags.
324  */
326 
327 /**
328  * Gets the general options associated with a CXIndex.
329  *
330  * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that
331  * are associated with the given CXIndex object.
332  */
334 
335 /**
336  * Sets the invocation emission path option in a CXIndex.
337  *
338  * The invocation emission path specifies a path which will contain log
339  * files for certain libclang invocations. A null value (default) implies that
340  * libclang invocations are not logged..
341  */
342 CINDEX_LINKAGE void
344 
345 /**
346  * Determine whether the given header is guarded against
347  * multiple inclusions, either with the conventional
348  * \#ifndef/\#define/\#endif macro guards or with \#pragma once.
349  */
351  CXFile file);
352 
353 /**
354  * Retrieve a file handle within the given translation unit.
355  *
356  * \param tu the translation unit
357  *
358  * \param file_name the name of the file.
359  *
360  * \returns the file handle for the named file in the translation unit \p tu,
361  * or a NULL file handle if the file was not a part of this translation unit.
362  */
364  const char *file_name);
365 
366 /**
367  * Retrieve the buffer associated with the given file.
368  *
369  * \param tu the translation unit
370  *
371  * \param file the file for which to retrieve the buffer.
372  *
373  * \param size [out] if non-NULL, will be set to the size of the buffer.
374  *
375  * \returns a pointer to the buffer in memory that holds the contents of
376  * \p file, or a NULL pointer when the file is not loaded.
377  */
379  CXFile file, size_t *size);
380 
381 /**
382  * Retrieves the source location associated with a given file/line/column
383  * in a particular translation unit.
384  */
386  CXFile file, unsigned line,
387  unsigned column);
388 /**
389  * Retrieves the source location associated with a given character offset
390  * in a particular translation unit.
391  */
393  CXFile file,
394  unsigned offset);
395 
396 /**
397  * Retrieve all ranges that were skipped by the preprocessor.
398  *
399  * The preprocessor will skip lines when they are surrounded by an
400  * if/ifdef/ifndef directive whose condition does not evaluate to true.
401  */
403  CXFile file);
404 
405 /**
406  * Retrieve all ranges from all files that were skipped by the
407  * preprocessor.
408  *
409  * The preprocessor will skip lines when they are surrounded by an
410  * if/ifdef/ifndef directive whose condition does not evaluate to true.
411  */
414 
415 /**
416  * Determine the number of diagnostics produced for the given
417  * translation unit.
418  */
420 
421 /**
422  * Retrieve a diagnostic associated with the given translation unit.
423  *
424  * \param Unit the translation unit to query.
425  * \param Index the zero-based diagnostic number to retrieve.
426  *
427  * \returns the requested diagnostic. This diagnostic must be freed
428  * via a call to \c clang_disposeDiagnostic().
429  */
431  unsigned Index);
432 
433 /**
434  * Retrieve the complete set of diagnostics associated with a
435  * translation unit.
436  *
437  * \param Unit the translation unit to query.
438  */
441 
442 /**
443  * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation
444  *
445  * The routines in this group provide the ability to create and destroy
446  * translation units from files, either by parsing the contents of the files or
447  * by reading in a serialized representation of a translation unit.
448  *
449  * @{
450  */
451 
452 /**
453  * Get the original translation unit source file name.
454  */
457 
458 /**
459  * Return the CXTranslationUnit for a given source file and the provided
460  * command line arguments one would pass to the compiler.
461  *
462  * Note: The 'source_filename' argument is optional. If the caller provides a
463  * NULL pointer, the name of the source file is expected to reside in the
464  * specified command line arguments.
465  *
466  * Note: When encountered in 'clang_command_line_args', the following options
467  * are ignored:
468  *
469  * '-c'
470  * '-emit-ast'
471  * '-fsyntax-only'
472  * '-o <output file>' (both '-o' and '<output file>' are ignored)
473  *
474  * \param CIdx The index object with which the translation unit will be
475  * associated.
476  *
477  * \param source_filename The name of the source file to load, or NULL if the
478  * source file is included in \p clang_command_line_args.
479  *
480  * \param num_clang_command_line_args The number of command-line arguments in
481  * \p clang_command_line_args.
482  *
483  * \param clang_command_line_args The command-line arguments that would be
484  * passed to the \c clang executable if it were being invoked out-of-process.
485  * These command-line options will be parsed and will affect how the translation
486  * unit is parsed. Note that the following options are ignored: '-c',
487  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.
488  *
489  * \param num_unsaved_files the number of unsaved file entries in \p
490  * unsaved_files.
491  *
492  * \param unsaved_files the files that have not yet been saved to disk
493  * but may be required for code completion, including the contents of
494  * those files. The contents and name of these files (as specified by
495  * CXUnsavedFile) are copied when necessary, so the client only needs to
496  * guarantee their validity until the call to this function returns.
497  */
499  CXIndex CIdx, const char *source_filename, int num_clang_command_line_args,
500  const char *const *clang_command_line_args, unsigned num_unsaved_files,
501  struct CXUnsavedFile *unsaved_files);
502 
503 /**
504  * Same as \c clang_createTranslationUnit2, but returns
505  * the \c CXTranslationUnit instead of an error code. In case of an error this
506  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
507  * error codes.
508  */
510 clang_createTranslationUnit(CXIndex CIdx, const char *ast_filename);
511 
512 /**
513  * Create a translation unit from an AST file (\c -emit-ast).
514  *
515  * \param[out] out_TU A non-NULL pointer to store the created
516  * \c CXTranslationUnit.
517  *
518  * \returns Zero on success, otherwise returns an error code.
519  */
521 clang_createTranslationUnit2(CXIndex CIdx, const char *ast_filename,
522  CXTranslationUnit *out_TU);
523 
524 /**
525  * Flags that control the creation of translation units.
526  *
527  * The enumerators in this enumeration type are meant to be bitwise
528  * ORed together to specify which options should be used when
529  * constructing the translation unit.
530  */
532  /**
533  * Used to indicate that no special translation-unit options are
534  * needed.
535  */
537 
538  /**
539  * Used to indicate that the parser should construct a "detailed"
540  * preprocessing record, including all macro definitions and instantiations.
541  *
542  * Constructing a detailed preprocessing record requires more memory
543  * and time to parse, since the information contained in the record
544  * is usually not retained. However, it can be useful for
545  * applications that require more detailed information about the
546  * behavior of the preprocessor.
547  */
549 
550  /**
551  * Used to indicate that the translation unit is incomplete.
552  *
553  * When a translation unit is considered "incomplete", semantic
554  * analysis that is typically performed at the end of the
555  * translation unit will be suppressed. For example, this suppresses
556  * the completion of tentative declarations in C and of
557  * instantiation of implicitly-instantiation function templates in
558  * C++. This option is typically used when parsing a header with the
559  * intent of producing a precompiled header.
560  */
562 
563  /**
564  * Used to indicate that the translation unit should be built with an
565  * implicit precompiled header for the preamble.
566  *
567  * An implicit precompiled header is used as an optimization when a
568  * particular translation unit is likely to be reparsed many times
569  * when the sources aren't changing that often. In this case, an
570  * implicit precompiled header will be built containing all of the
571  * initial includes at the top of the main file (what we refer to as
572  * the "preamble" of the file). In subsequent parses, if the
573  * preamble or the files in it have not changed, \c
574  * clang_reparseTranslationUnit() will re-use the implicit
575  * precompiled header to improve parsing performance.
576  */
578 
579  /**
580  * Used to indicate that the translation unit should cache some
581  * code-completion results with each reparse of the source file.
582  *
583  * Caching of code-completion results is a performance optimization that
584  * introduces some overhead to reparsing but improves the performance of
585  * code-completion operations.
586  */
588 
589  /**
590  * Used to indicate that the translation unit will be serialized with
591  * \c clang_saveTranslationUnit.
592  *
593  * This option is typically used when parsing a header with the intent of
594  * producing a precompiled header.
595  */
597 
598  /**
599  * DEPRECATED: Enabled chained precompiled preambles in C++.
600  *
601  * Note: this is a *temporary* option that is available only while
602  * we are testing C++ precompiled preamble support. It is deprecated.
603  */
605 
606  /**
607  * Used to indicate that function/method bodies should be skipped while
608  * parsing.
609  *
610  * This option can be used to search for declarations/definitions while
611  * ignoring the usages.
612  */
614 
615  /**
616  * Used to indicate that brief documentation comments should be
617  * included into the set of code completions returned from this translation
618  * unit.
619  */
621 
622  /**
623  * Used to indicate that the precompiled preamble should be created on
624  * the first parse. Otherwise it will be created on the first reparse. This
625  * trades runtime on the first parse (serializing the preamble takes time) for
626  * reduced runtime on the second parse (can now reuse the preamble).
627  */
629 
630  /**
631  * Do not stop processing when fatal errors are encountered.
632  *
633  * When fatal errors are encountered while parsing a translation unit,
634  * semantic analysis is typically stopped early when compiling code. A common
635  * source for fatal errors are unresolvable include files. For the
636  * purposes of an IDE, this is undesirable behavior and as much information
637  * as possible should be reported. Use this flag to enable this behavior.
638  */
640 
641  /**
642  * Sets the preprocessor in a mode for parsing a single file only.
643  */
645 
646  /**
647  * Used in combination with CXTranslationUnit_SkipFunctionBodies to
648  * constrain the skipping of function bodies to the preamble.
649  *
650  * The function bodies of the main file are not skipped.
651  */
653 
654  /**
655  * Used to indicate that attributed types should be included in CXType.
656  */
658 
659  /**
660  * Used to indicate that implicit attributes should be visited.
661  */
663 
664  /**
665  * Used to indicate that non-errors from included files should be ignored.
666  *
667  * If set, clang_getDiagnosticSetFromTU() will not report e.g. warnings from
668  * included files anymore. This speeds up clang_getDiagnosticSetFromTU() for
669  * the case where these warnings are not of interest, as for an IDE for
670  * example, which typically shows only the diagnostics in the main file.
671  */
673 
674  /**
675  * Tells the preprocessor not to skip excluded conditional blocks.
676  */
678 };
679 
680 /**
681  * Returns the set of flags that is suitable for parsing a translation
682  * unit that is being edited.
683  *
684  * The set of flags returned provide options for \c clang_parseTranslationUnit()
685  * to indicate that the translation unit is likely to be reparsed many times,
686  * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly
687  * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag
688  * set contains an unspecified set of optimizations (e.g., the precompiled
689  * preamble) geared toward improving the performance of these routines. The
690  * set of optimizations enabled may change from one version to the next.
691  */
693 
694 /**
695  * Same as \c clang_parseTranslationUnit2, but returns
696  * the \c CXTranslationUnit instead of an error code. In case of an error this
697  * routine returns a \c NULL \c CXTranslationUnit, without further detailed
698  * error codes.
699  */
701  CXIndex CIdx, const char *source_filename,
702  const char *const *command_line_args, int num_command_line_args,
703  struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
704  unsigned options);
705 
706 /**
707  * Parse the given source file and the translation unit corresponding
708  * to that file.
709  *
710  * This routine is the main entry point for the Clang C API, providing the
711  * ability to parse a source file into a translation unit that can then be
712  * queried by other functions in the API. This routine accepts a set of
713  * command-line arguments so that the compilation can be configured in the same
714  * way that the compiler is configured on the command line.
715  *
716  * \param CIdx The index object with which the translation unit will be
717  * associated.
718  *
719  * \param source_filename The name of the source file to load, or NULL if the
720  * source file is included in \c command_line_args.
721  *
722  * \param command_line_args The command-line arguments that would be
723  * passed to the \c clang executable if it were being invoked out-of-process.
724  * These command-line options will be parsed and will affect how the translation
725  * unit is parsed. Note that the following options are ignored: '-c',
726  * '-emit-ast', '-fsyntax-only' (which is the default), and '-o <output file>'.
727  *
728  * \param num_command_line_args The number of command-line arguments in
729  * \c command_line_args.
730  *
731  * \param unsaved_files the files that have not yet been saved to disk
732  * but may be required for parsing, including the contents of
733  * those files. The contents and name of these files (as specified by
734  * CXUnsavedFile) are copied when necessary, so the client only needs to
735  * guarantee their validity until the call to this function returns.
736  *
737  * \param num_unsaved_files the number of unsaved file entries in \p
738  * unsaved_files.
739  *
740  * \param options A bitmask of options that affects how the translation unit
741  * is managed but not its compilation. This should be a bitwise OR of the
742  * CXTranslationUnit_XXX flags.
743  *
744  * \param[out] out_TU A non-NULL pointer to store the created
745  * \c CXTranslationUnit, describing the parsed code and containing any
746  * diagnostics produced by the compiler.
747  *
748  * \returns Zero on success, otherwise returns an error code.
749  */
751  CXIndex CIdx, const char *source_filename,
752  const char *const *command_line_args, int num_command_line_args,
753  struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
754  unsigned options, CXTranslationUnit *out_TU);
755 
756 /**
757  * Same as clang_parseTranslationUnit2 but requires a full command line
758  * for \c command_line_args including argv[0]. This is useful if the standard
759  * library paths are relative to the binary.
760  */
762  CXIndex CIdx, const char *source_filename,
763  const char *const *command_line_args, int num_command_line_args,
764  struct CXUnsavedFile *unsaved_files, unsigned num_unsaved_files,
765  unsigned options, CXTranslationUnit *out_TU);
766 
767 /**
768  * Flags that control how translation units are saved.
769  *
770  * The enumerators in this enumeration type are meant to be bitwise
771  * ORed together to specify which options should be used when
772  * saving the translation unit.
773  */
775  /**
776  * Used to indicate that no special saving options are needed.
777  */
779 };
780 
781 /**
782  * Returns the set of flags that is suitable for saving a translation
783  * unit.
784  *
785  * The set of flags returned provide options for
786  * \c clang_saveTranslationUnit() by default. The returned flag
787  * set contains an unspecified set of options that save translation units with
788  * the most commonly-requested data.
789  */
791 
792 /**
793  * Describes the kind of error that occurred (if any) in a call to
794  * \c clang_saveTranslationUnit().
795  */
797  /**
798  * Indicates that no error occurred while saving a translation unit.
799  */
801 
802  /**
803  * Indicates that an unknown error occurred while attempting to save
804  * the file.
805  *
806  * This error typically indicates that file I/O failed when attempting to
807  * write the file.
808  */
810 
811  /**
812  * Indicates that errors during translation prevented this attempt
813  * to save the translation unit.
814  *
815  * Errors that prevent the translation unit from being saved can be
816  * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic().
817  */
819 
820  /**
821  * Indicates that the translation unit to be saved was somehow
822  * invalid (e.g., NULL).
823  */
825 };
826 
827 /**
828  * Saves a translation unit into a serialized representation of
829  * that translation unit on disk.
830  *
831  * Any translation unit that was parsed without error can be saved
832  * into a file. The translation unit can then be deserialized into a
833  * new \c CXTranslationUnit with \c clang_createTranslationUnit() or,
834  * if it is an incomplete translation unit that corresponds to a
835  * header, used as a precompiled header when parsing other translation
836  * units.
837  *
838  * \param TU The translation unit to save.
839  *
840  * \param FileName The file to which the translation unit will be saved.
841  *
842  * \param options A bitmask of options that affects how the translation unit
843  * is saved. This should be a bitwise OR of the
844  * CXSaveTranslationUnit_XXX flags.
845  *
846  * \returns A value that will match one of the enumerators of the CXSaveError
847  * enumeration. Zero (CXSaveError_None) indicates that the translation unit was
848  * saved successfully, while a non-zero value indicates that a problem occurred.
849  */
851  const char *FileName,
852  unsigned options);
853 
854 /**
855  * Suspend a translation unit in order to free memory associated with it.
856  *
857  * A suspended translation unit uses significantly less memory but on the other
858  * side does not support any other calls than \c clang_reparseTranslationUnit
859  * to resume it or \c clang_disposeTranslationUnit to dispose it completely.
860  */
862 
863 /**
864  * Destroy the specified CXTranslationUnit object.
865  */
867 
868 /**
869  * Flags that control the reparsing of translation units.
870  *
871  * The enumerators in this enumeration type are meant to be bitwise
872  * ORed together to specify which options should be used when
873  * reparsing the translation unit.
874  */
876  /**
877  * Used to indicate that no special reparsing options are needed.
878  */
880 };
881 
882 /**
883  * Returns the set of flags that is suitable for reparsing a translation
884  * unit.
885  *
886  * The set of flags returned provide options for
887  * \c clang_reparseTranslationUnit() by default. The returned flag
888  * set contains an unspecified set of optimizations geared toward common uses
889  * of reparsing. The set of optimizations enabled may change from one version
890  * to the next.
891  */
893 
894 /**
895  * Reparse the source files that produced this translation unit.
896  *
897  * This routine can be used to re-parse the source files that originally
898  * created the given translation unit, for example because those source files
899  * have changed (either on disk or as passed via \p unsaved_files). The
900  * source code will be reparsed with the same command-line options as it
901  * was originally parsed.
902  *
903  * Reparsing a translation unit invalidates all cursors and source locations
904  * that refer into that translation unit. This makes reparsing a translation
905  * unit semantically equivalent to destroying the translation unit and then
906  * creating a new translation unit with the same command-line arguments.
907  * However, it may be more efficient to reparse a translation
908  * unit using this routine.
909  *
910  * \param TU The translation unit whose contents will be re-parsed. The
911  * translation unit must originally have been built with
912  * \c clang_createTranslationUnitFromSourceFile().
913  *
914  * \param num_unsaved_files The number of unsaved file entries in \p
915  * unsaved_files.
916  *
917  * \param unsaved_files The files that have not yet been saved to disk
918  * but may be required for parsing, including the contents of
919  * those files. The contents and name of these files (as specified by
920  * CXUnsavedFile) are copied when necessary, so the client only needs to
921  * guarantee their validity until the call to this function returns.
922  *
923  * \param options A bitset of options composed of the flags in CXReparse_Flags.
924  * The function \c clang_defaultReparseOptions() produces a default set of
925  * options recommended for most uses, based on the translation unit.
926  *
927  * \returns 0 if the sources could be reparsed. A non-zero error code will be
928  * returned if reparsing was impossible, such that the translation unit is
929  * invalid. In such cases, the only valid call for \c TU is
930  * \c clang_disposeTranslationUnit(TU). The error codes returned by this
931  * routine are described by the \c CXErrorCode enum.
932  */
933 CINDEX_LINKAGE int
934 clang_reparseTranslationUnit(CXTranslationUnit TU, unsigned num_unsaved_files,
935  struct CXUnsavedFile *unsaved_files,
936  unsigned options);
937 
938 /**
939  * Categorizes how memory is being used by a translation unit.
940  */
959 
962 };
963 
964 /**
965  * Returns the human-readable null-terminated C string that represents
966  * the name of the memory category. This string should never be freed.
967  */
970 
971 typedef struct CXTUResourceUsageEntry {
972  /* The memory usage category. */
974  /* Amount of resources used.
975  The units will depend on the resource kind. */
976  unsigned long amount;
978 
979 /**
980  * The memory usage of a CXTranslationUnit, broken into categories.
981  */
982 typedef struct CXTUResourceUsage {
983  /* Private data member, used for queries. */
984  void *data;
985 
986  /* The number of entries in the 'entries' array. */
987  unsigned numEntries;
988 
989  /* An array of key-value pairs, representing the breakdown of memory
990  usage. */
992 
994 
995 /**
996  * Return the memory usage of a translation unit. This object
997  * should be released with clang_disposeCXTUResourceUsage().
998  */
1001 
1003 
1004 /**
1005  * Get target information for this translation unit.
1006  *
1007  * The CXTargetInfo object cannot outlive the CXTranslationUnit object.
1008  */
1011 
1012 /**
1013  * Destroy the CXTargetInfo object.
1014  */
1016 
1017 /**
1018  * Get the normalized target triple as a string.
1019  *
1020  * Returns the empty string in case of any error.
1021  */
1023 
1024 /**
1025  * Get the pointer width of the target in bits.
1026  *
1027  * Returns -1 in case of error.
1028  */
1030 
1031 /**
1032  * @}
1033  */
1034 
1035 /**
1036  * Describes the kind of entity that a cursor refers to.
1037  */
1039  /* Declarations */
1040  /**
1041  * A declaration whose specific kind is not exposed via this
1042  * interface.
1043  *
1044  * Unexposed declarations have the same operations as any other kind
1045  * of declaration; one can extract their location information,
1046  * spelling, find their definitions, etc. However, the specific kind
1047  * of the declaration is not reported.
1048  */
1050  /** A C or C++ struct. */
1052  /** A C or C++ union. */
1054  /** A C++ class. */
1056  /** An enumeration. */
1058  /**
1059  * A field (in C) or non-static data member (in C++) in a
1060  * struct, union, or C++ class.
1061  */
1063  /** An enumerator constant. */
1065  /** A function. */
1067  /** A variable. */
1069  /** A function or method parameter. */
1071  /** An Objective-C \@interface. */
1073  /** An Objective-C \@interface for a category. */
1075  /** An Objective-C \@protocol declaration. */
1077  /** An Objective-C \@property declaration. */
1079  /** An Objective-C instance variable. */
1081  /** An Objective-C instance method. */
1083  /** An Objective-C class method. */
1085  /** An Objective-C \@implementation. */
1087  /** An Objective-C \@implementation for a category. */
1089  /** A typedef. */
1091  /** A C++ class method. */
1093  /** A C++ namespace. */
1095  /** A linkage specification, e.g. 'extern "C"'. */
1097  /** A C++ constructor. */
1099  /** A C++ destructor. */
1101  /** A C++ conversion function. */
1103  /** A C++ template type parameter. */
1105  /** A C++ non-type template parameter. */
1107  /** A C++ template template parameter. */
1109  /** A C++ function template. */
1111  /** A C++ class template. */
1113  /** A C++ class template partial specialization. */
1115  /** A C++ namespace alias declaration. */
1117  /** A C++ using directive. */
1119  /** A C++ using declaration. */
1121  /** A C++ alias declaration */
1123  /** An Objective-C \@synthesize definition. */
1125  /** An Objective-C \@dynamic definition. */
1127  /** An access specifier. */
1129 
1132 
1133  /* References */
1134  CXCursor_FirstRef = 40, /* Decl references */
1138  /**
1139  * A reference to a type declaration.
1140  *
1141  * A type reference occurs anywhere where a type is named but not
1142  * declared. For example, given:
1143  *
1144  * \code
1145  * typedef unsigned size_type;
1146  * size_type size;
1147  * \endcode
1148  *
1149  * The typedef is a declaration of size_type (CXCursor_TypedefDecl),
1150  * while the type of the variable "size" is referenced. The cursor
1151  * referenced by the type of size is the typedef for size_type.
1152  */
1155  /**
1156  * A reference to a class template, function template, template
1157  * template parameter, or class template partial specialization.
1158  */
1160  /**
1161  * A reference to a namespace or namespace alias.
1162  */
1164  /**
1165  * A reference to a member of a struct, union, or class that occurs in
1166  * some non-expression context, e.g., a designated initializer.
1167  */
1169  /**
1170  * A reference to a labeled statement.
1171  *
1172  * This cursor kind is used to describe the jump to "start_over" in the
1173  * goto statement in the following example:
1174  *
1175  * \code
1176  * start_over:
1177  * ++counter;
1178  *
1179  * goto start_over;
1180  * \endcode
1181  *
1182  * A label reference cursor refers to a label statement.
1183  */
1185 
1186  /**
1187  * A reference to a set of overloaded functions or function templates
1188  * that has not yet been resolved to a specific function or function template.
1189  *
1190  * An overloaded declaration reference cursor occurs in C++ templates where
1191  * a dependent name refers to a function. For example:
1192  *
1193  * \code
1194  * template<typename T> void swap(T&, T&);
1195  *
1196  * struct X { ... };
1197  * void swap(X&, X&);
1198  *
1199  * template<typename T>
1200  * void reverse(T* first, T* last) {
1201  * while (first < last - 1) {
1202  * swap(*first, *--last);
1203  * ++first;
1204  * }
1205  * }
1206  *
1207  * struct Y { };
1208  * void swap(Y&, Y&);
1209  * \endcode
1210  *
1211  * Here, the identifier "swap" is associated with an overloaded declaration
1212  * reference. In the template definition, "swap" refers to either of the two
1213  * "swap" functions declared above, so both results will be available. At
1214  * instantiation time, "swap" may also refer to other functions found via
1215  * argument-dependent lookup (e.g., the "swap" function at the end of the
1216  * example).
1217  *
1218  * The functions \c clang_getNumOverloadedDecls() and
1219  * \c clang_getOverloadedDecl() can be used to retrieve the definitions
1220  * referenced by this cursor.
1221  */
1223 
1224  /**
1225  * A reference to a variable that occurs in some non-expression
1226  * context, e.g., a C++ lambda capture list.
1227  */
1229 
1231 
1232  /* Error conditions */
1239 
1240  /* Expressions */
1242 
1243  /**
1244  * An expression whose specific kind is not exposed via this
1245  * interface.
1246  *
1247  * Unexposed expressions have the same operations as any other kind
1248  * of expression; one can extract their location information,
1249  * spelling, children, etc. However, the specific kind of the
1250  * expression is not reported.
1251  */
1253 
1254  /**
1255  * An expression that refers to some value declaration, such
1256  * as a function, variable, or enumerator.
1257  */
1259 
1260  /**
1261  * An expression that refers to a member of a struct, union,
1262  * class, Objective-C class, etc.
1263  */
1265 
1266  /** An expression that calls a function. */
1268 
1269  /** An expression that sends a message to an Objective-C
1270  object or class. */
1272 
1273  /** An expression that represents a block literal. */
1275 
1276  /** An integer literal.
1277  */
1279 
1280  /** A floating point number literal.
1281  */
1283 
1284  /** An imaginary number literal.
1285  */
1287 
1288  /** A string literal.
1289  */
1291 
1292  /** A character literal.
1293  */
1295 
1296  /** A parenthesized expression, e.g. "(1)".
1297  *
1298  * This AST node is only formed if full location information is requested.
1299  */
1301 
1302  /** This represents the unary-expression's (except sizeof and
1303  * alignof).
1304  */
1306 
1307  /** [C99 6.5.2.1] Array Subscripting.
1308  */
1310 
1311  /** A builtin binary operation expression such as "x + y" or
1312  * "x <= y".
1313  */
1315 
1316  /** Compound assignment such as "+=".
1317  */
1319 
1320  /** The ?: ternary operator.
1321  */
1323 
1324  /** An explicit cast in C (C99 6.5.4) or a C-style cast in C++
1325  * (C++ [expr.cast]), which uses the syntax (Type)expr.
1326  *
1327  * For example: (int)f.
1328  */
1330 
1331  /** [C99 6.5.2.5]
1332  */
1334 
1335  /** Describes an C or C++ initializer list.
1336  */
1338 
1339  /** The GNU address of label extension, representing &&label.
1340  */
1342 
1343  /** This is the GNU Statement Expression extension: ({int X=4; X;})
1344  */
1346 
1347  /** Represents a C11 generic selection.
1348  */
1350 
1351  /** Implements the GNU __null extension, which is a name for a null
1352  * pointer constant that has integral type (e.g., int or long) and is the same
1353  * size and alignment as a pointer.
1354  *
1355  * The __null extension is typically only used by system headers, which define
1356  * NULL as __null in C++ rather than using 0 (which is an integer that may not
1357  * match the size of a pointer).
1358  */
1360 
1361  /** C++'s static_cast<> expression.
1362  */
1364 
1365  /** C++'s dynamic_cast<> expression.
1366  */
1368 
1369  /** C++'s reinterpret_cast<> expression.
1370  */
1372 
1373  /** C++'s const_cast<> expression.
1374  */
1376 
1377  /** Represents an explicit C++ type conversion that uses "functional"
1378  * notion (C++ [expr.type.conv]).
1379  *
1380  * Example:
1381  * \code
1382  * x = int(0.5);
1383  * \endcode
1384  */
1386 
1387  /** A C++ typeid expression (C++ [expr.typeid]).
1388  */
1390 
1391  /** [C++ 2.13.5] C++ Boolean Literal.
1392  */
1394 
1395  /** [C++0x 2.14.7] C++ Pointer Literal.
1396  */
1398 
1399  /** Represents the "this" expression in C++
1400  */
1402 
1403  /** [C++ 15] C++ Throw Expression.
1404  *
1405  * This handles 'throw' and 'throw' assignment-expression. When
1406  * assignment-expression isn't present, Op will be null.
1407  */
1409 
1410  /** A new expression for memory allocation and constructor calls, e.g:
1411  * "new CXXNewExpr(foo)".
1412  */
1414 
1415  /** A delete expression for memory deallocation and destructor calls,
1416  * e.g. "delete[] pArray".
1417  */
1419 
1420  /** A unary expression. (noexcept, sizeof, or other traits)
1421  */
1423 
1424  /** An Objective-C string literal i.e. @"foo".
1425  */
1427 
1428  /** An Objective-C \@encode expression.
1429  */
1431 
1432  /** An Objective-C \@selector expression.
1433  */
1435 
1436  /** An Objective-C \@protocol expression.
1437  */
1439 
1440  /** An Objective-C "bridged" cast expression, which casts between
1441  * Objective-C pointers and C pointers, transferring ownership in the process.
1442  *
1443  * \code
1444  * NSString *str = (__bridge_transfer NSString *)CFCreateString();
1445  * \endcode
1446  */
1448 
1449  /** Represents a C++0x pack expansion that produces a sequence of
1450  * expressions.
1451  *
1452  * A pack expansion expression contains a pattern (which itself is an
1453  * expression) followed by an ellipsis. For example:
1454  *
1455  * \code
1456  * template<typename F, typename ...Types>
1457  * void forward(F f, Types &&...args) {
1458  * f(static_cast<Types&&>(args)...);
1459  * }
1460  * \endcode
1461  */
1463 
1464  /** Represents an expression that computes the length of a parameter
1465  * pack.
1466  *
1467  * \code
1468  * template<typename ...Types>
1469  * struct count {
1470  * static const unsigned value = sizeof...(Types);
1471  * };
1472  * \endcode
1473  */
1475 
1476  /* Represents a C++ lambda expression that produces a local function
1477  * object.
1478  *
1479  * \code
1480  * void abssort(float *x, unsigned N) {
1481  * std::sort(x, x + N,
1482  * [](float a, float b) {
1483  * return std::abs(a) < std::abs(b);
1484  * });
1485  * }
1486  * \endcode
1487  */
1489 
1490  /** Objective-c Boolean Literal.
1491  */
1493 
1494  /** Represents the "self" expression in an Objective-C method.
1495  */
1497 
1498  /** OpenMP 5.0 [2.1.5, Array Section].
1499  */
1501 
1502  /** Represents an @available(...) check.
1503  */
1505 
1506  /**
1507  * Fixed point literal
1508  */
1510 
1511  /** OpenMP 5.0 [2.1.4, Array Shaping].
1512  */
1514 
1515  /**
1516  * OpenMP 5.0 [2.1.6 Iterators]
1517  */
1519 
1520  /** OpenCL's addrspace_cast<> expression.
1521  */
1523 
1524  /**
1525  * Expression that references a C++20 concept.
1526  */
1528 
1529  /**
1530  * Expression that references a C++20 concept.
1531  */
1533 
1535 
1536  /* Statements */
1538  /**
1539  * A statement whose specific kind is not exposed via this
1540  * interface.
1541  *
1542  * Unexposed statements have the same operations as any other kind of
1543  * statement; one can extract their location information, spelling,
1544  * children, etc. However, the specific kind of the statement is not
1545  * reported.
1546  */
1548 
1549  /** A labelled statement in a function.
1550  *
1551  * This cursor kind is used to describe the "start_over:" label statement in
1552  * the following example:
1553  *
1554  * \code
1555  * start_over:
1556  * ++counter;
1557  * \endcode
1558  *
1559  */
1561 
1562  /** A group of statements like { stmt stmt }.
1563  *
1564  * This cursor kind is used to describe compound statements, e.g. function
1565  * bodies.
1566  */
1568 
1569  /** A case statement.
1570  */
1572 
1573  /** A default statement.
1574  */
1576 
1577  /** An if statement
1578  */
1580 
1581  /** A switch statement.
1582  */
1584 
1585  /** A while statement.
1586  */
1588 
1589  /** A do statement.
1590  */
1592 
1593  /** A for statement.
1594  */
1596 
1597  /** A goto statement.
1598  */
1600 
1601  /** An indirect goto statement.
1602  */
1604 
1605  /** A continue statement.
1606  */
1608 
1609  /** A break statement.
1610  */
1612 
1613  /** A return statement.
1614  */
1616 
1617  /** A GCC inline assembly statement extension.
1618  */
1621 
1622  /** Objective-C's overall \@try-\@catch-\@finally statement.
1623  */
1625 
1626  /** Objective-C's \@catch statement.
1627  */
1629 
1630  /** Objective-C's \@finally statement.
1631  */
1633 
1634  /** Objective-C's \@throw statement.
1635  */
1637 
1638  /** Objective-C's \@synchronized statement.
1639  */
1641 
1642  /** Objective-C's autorelease pool statement.
1643  */
1645 
1646  /** Objective-C's collection statement.
1647  */
1649 
1650  /** C++'s catch statement.
1651  */
1653 
1654  /** C++'s try statement.
1655  */
1657 
1658  /** C++'s for (* : *) statement.
1659  */
1661 
1662  /** Windows Structured Exception Handling's try statement.
1663  */
1665 
1666  /** Windows Structured Exception Handling's except statement.
1667  */
1669 
1670  /** Windows Structured Exception Handling's finally statement.
1671  */
1673 
1674  /** A MS inline assembly statement extension.
1675  */
1677 
1678  /** The null statement ";": C99 6.8.3p3.
1679  *
1680  * This cursor kind is used to describe the null statement.
1681  */
1683 
1684  /** Adaptor class for mixing declarations with statements and
1685  * expressions.
1686  */
1688 
1689  /** OpenMP parallel directive.
1690  */
1692 
1693  /** OpenMP SIMD directive.
1694  */
1696 
1697  /** OpenMP for directive.
1698  */
1700 
1701  /** OpenMP sections directive.
1702  */
1704 
1705  /** OpenMP section directive.
1706  */
1708 
1709  /** OpenMP single directive.
1710  */
1712 
1713  /** OpenMP parallel for directive.
1714  */
1716 
1717  /** OpenMP parallel sections directive.
1718  */
1720 
1721  /** OpenMP task directive.
1722  */
1724 
1725  /** OpenMP master directive.
1726  */
1728 
1729  /** OpenMP critical directive.
1730  */
1732 
1733  /** OpenMP taskyield directive.
1734  */
1736 
1737  /** OpenMP barrier directive.
1738  */
1740 
1741  /** OpenMP taskwait directive.
1742  */
1744 
1745  /** OpenMP flush directive.
1746  */
1748 
1749  /** Windows Structured Exception Handling's leave statement.
1750  */
1752 
1753  /** OpenMP ordered directive.
1754  */
1756 
1757  /** OpenMP atomic directive.
1758  */
1760 
1761  /** OpenMP for SIMD directive.
1762  */
1764 
1765  /** OpenMP parallel for SIMD directive.
1766  */
1768 
1769  /** OpenMP target directive.
1770  */
1772 
1773  /** OpenMP teams directive.
1774  */
1776 
1777  /** OpenMP taskgroup directive.
1778  */
1780 
1781  /** OpenMP cancellation point directive.
1782  */
1784 
1785  /** OpenMP cancel directive.
1786  */
1788 
1789  /** OpenMP target data directive.
1790  */
1792 
1793  /** OpenMP taskloop directive.
1794  */
1796 
1797  /** OpenMP taskloop simd directive.
1798  */
1800 
1801  /** OpenMP distribute directive.
1802  */
1804 
1805  /** OpenMP target enter data directive.
1806  */
1808 
1809  /** OpenMP target exit data directive.
1810  */
1812 
1813  /** OpenMP target parallel directive.
1814  */
1816 
1817  /** OpenMP target parallel for directive.
1818  */
1820 
1821  /** OpenMP target update directive.
1822  */
1824 
1825  /** OpenMP distribute parallel for directive.
1826  */
1828 
1829  /** OpenMP distribute parallel for simd directive.
1830  */
1832 
1833  /** OpenMP distribute simd directive.
1834  */
1836 
1837  /** OpenMP target parallel for simd directive.
1838  */
1840 
1841  /** OpenMP target simd directive.
1842  */
1844 
1845  /** OpenMP teams distribute directive.
1846  */
1848 
1849  /** OpenMP teams distribute simd directive.
1850  */
1852 
1853  /** OpenMP teams distribute parallel for simd directive.
1854  */
1856 
1857  /** OpenMP teams distribute parallel for directive.
1858  */
1860 
1861  /** OpenMP target teams directive.
1862  */
1864 
1865  /** OpenMP target teams distribute directive.
1866  */
1868 
1869  /** OpenMP target teams distribute parallel for directive.
1870  */
1872 
1873  /** OpenMP target teams distribute parallel for simd directive.
1874  */
1876 
1877  /** OpenMP target teams distribute simd directive.
1878  */
1880 
1881  /** C++2a std::bit_cast expression.
1882  */
1884 
1885  /** OpenMP master taskloop directive.
1886  */
1888 
1889  /** OpenMP parallel master taskloop directive.
1890  */
1892 
1893  /** OpenMP master taskloop simd directive.
1894  */
1896 
1897  /** OpenMP parallel master taskloop simd directive.
1898  */
1900 
1901  /** OpenMP parallel master directive.
1902  */
1904 
1905  /** OpenMP depobj directive.
1906  */
1908 
1909  /** OpenMP scan directive.
1910  */
1912 
1913  /** OpenMP tile directive.
1914  */
1916 
1917  /** OpenMP canonical loop.
1918  */
1920 
1921  /** OpenMP interop directive.
1922  */
1924 
1925  /** OpenMP dispatch directive.
1926  */
1928 
1929  /** OpenMP masked directive.
1930  */
1932 
1933  /** OpenMP unroll directive.
1934  */
1936 
1937  /** OpenMP metadirective directive.
1938  */
1940 
1941  /** OpenMP loop directive.
1942  */
1944 
1945  /** OpenMP teams loop directive.
1946  */
1948 
1949  /** OpenMP target teams loop directive.
1950  */
1952 
1953  /** OpenMP parallel loop directive.
1954  */
1956 
1957  /** OpenMP target parallel loop directive.
1958  */
1960 
1961  /** OpenMP parallel masked directive.
1962  */
1964 
1965  /** OpenMP masked taskloop directive.
1966  */
1968 
1969  /** OpenMP masked taskloop simd directive.
1970  */
1972 
1973  /** OpenMP parallel masked taskloop directive.
1974  */
1976 
1977  /** OpenMP parallel masked taskloop simd directive.
1978  */
1980 
1981  /** OpenMP error directive.
1982  */
1984 
1986 
1987  /**
1988  * Cursor that represents the translation unit itself.
1989  *
1990  * The translation unit cursor exists primarily to act as the root
1991  * cursor for traversing the contents of a translation unit.
1992  */
1994 
1995  /* Attributes */
1997  /**
1998  * An attribute whose specific kind is not exposed via this
1999  * interface.
2000  */
2002 
2045 
2046  /* Preprocessing */
2054 
2055  /* Extra Declarations */
2056  /**
2057  * A module import declaration.
2058  */
2061  /**
2062  * A static_assert or _Static_assert node
2063  */
2065  /**
2066  * a friend declaration.
2067  */
2069  /**
2070  * a concept declaration.
2071  */
2073 
2076 
2077  /**
2078  * A code completion overload candidate.
2079  */
2081 };
2082 
2083 /**
2084  * A cursor representing some element in the abstract syntax tree for
2085  * a translation unit.
2086  *
2087  * The cursor abstraction unifies the different kinds of entities in a
2088  * program--declaration, statements, expressions, references to declarations,
2089  * etc.--under a single "cursor" abstraction with a common set of operations.
2090  * Common operation for a cursor include: getting the physical location in
2091  * a source file where the cursor points, getting the name associated with a
2092  * cursor, and retrieving cursors for any child nodes of a particular cursor.
2093  *
2094  * Cursors can be produced in two specific ways.
2095  * clang_getTranslationUnitCursor() produces a cursor for a translation unit,
2096  * from which one can use clang_visitChildren() to explore the rest of the
2097  * translation unit. clang_getCursor() maps from a physical source location
2098  * to the entity that resides at that location, allowing one to map from the
2099  * source code into the AST.
2100  */
2101 typedef struct {
2103  int xdata;
2104  const void *data[3];
2105 } CXCursor;
2106 
2107 /**
2108  * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations
2109  *
2110  * @{
2111  */
2112 
2113 /**
2114  * Retrieve the NULL cursor, which represents no entity.
2115  */
2117 
2118 /**
2119  * Retrieve the cursor that represents the given translation unit.
2120  *
2121  * The translation unit cursor can be used to start traversing the
2122  * various declarations within the given translation unit.
2123  */
2125 
2126 /**
2127  * Determine whether two cursors are equivalent.
2128  */
2130 
2131 /**
2132  * Returns non-zero if \p cursor is null.
2133  */
2135 
2136 /**
2137  * Compute a hash value for the given cursor.
2138  */
2140 
2141 /**
2142  * Retrieve the kind of the given cursor.
2143  */
2145 
2146 /**
2147  * Determine whether the given cursor kind represents a declaration.
2148  */
2150 
2151 /**
2152  * Determine whether the given declaration is invalid.
2153  *
2154  * A declaration is invalid if it could not be parsed successfully.
2155  *
2156  * \returns non-zero if the cursor represents a declaration and it is
2157  * invalid, otherwise NULL.
2158  */
2160 
2161 /**
2162  * Determine whether the given cursor kind represents a simple
2163  * reference.
2164  *
2165  * Note that other kinds of cursors (such as expressions) can also refer to
2166  * other cursors. Use clang_getCursorReferenced() to determine whether a
2167  * particular cursor refers to another entity.
2168  */
2170 
2171 /**
2172  * Determine whether the given cursor kind represents an expression.
2173  */
2175 
2176 /**
2177  * Determine whether the given cursor kind represents a statement.
2178  */
2180 
2181 /**
2182  * Determine whether the given cursor kind represents an attribute.
2183  */
2185 
2186 /**
2187  * Determine whether the given cursor has any attributes.
2188  */
2190 
2191 /**
2192  * Determine whether the given cursor kind represents an invalid
2193  * cursor.
2194  */
2196 
2197 /**
2198  * Determine whether the given cursor kind represents a translation
2199  * unit.
2200  */
2202 
2203 /***
2204  * Determine whether the given cursor represents a preprocessing
2205  * element, such as a preprocessor directive or macro instantiation.
2206  */
2208 
2209 /***
2210  * Determine whether the given cursor represents a currently
2211  * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt).
2212  */
2214 
2215 /**
2216  * Describe the linkage of the entity referred to by a cursor.
2217  */
2219  /** This value indicates that no linkage information is available
2220  * for a provided CXCursor. */
2222  /**
2223  * This is the linkage for variables, parameters, and so on that
2224  * have automatic storage. This covers normal (non-extern) local variables.
2225  */
2227  /** This is the linkage for static variables and static functions. */
2229  /** This is the linkage for entities with external linkage that live
2230  * in C++ anonymous namespaces.*/
2232  /** This is the linkage for entities with true, external linkage. */
2234 };
2235 
2236 /**
2237  * Determine the linkage of the entity referred to by a given cursor.
2238  */
2240 
2242  /** This value indicates that no visibility information is available
2243  * for a provided CXCursor. */
2245 
2246  /** Symbol not seen by the linker. */
2248  /** Symbol seen by the linker but resolves to a symbol inside this object. */
2250  /** Symbol seen by the linker and acts like a normal symbol. */
2252 };
2253 
2254 /**
2255  * Describe the visibility of the entity referred to by a cursor.
2256  *
2257  * This returns the default visibility if not explicitly specified by
2258  * a visibility attribute. The default visibility may be changed by
2259  * commandline arguments.
2260  *
2261  * \param cursor The cursor to query.
2262  *
2263  * \returns The visibility of the cursor.
2264  */
2266 
2267 /**
2268  * Determine the availability of the entity that this cursor refers to,
2269  * taking the current target platform into account.
2270  *
2271  * \param cursor The cursor to query.
2272  *
2273  * \returns The availability of the cursor.
2274  */
2277 
2278 /**
2279  * Describes the availability of a given entity on a particular platform, e.g.,
2280  * a particular class might only be available on Mac OS 10.7 or newer.
2281  */
2282 typedef struct CXPlatformAvailability {
2283  /**
2284  * A string that describes the platform for which this structure
2285  * provides availability information.
2286  *
2287  * Possible values are "ios" or "macos".
2288  */
2290  /**
2291  * The version number in which this entity was introduced.
2292  */
2294  /**
2295  * The version number in which this entity was deprecated (but is
2296  * still available).
2297  */
2299  /**
2300  * The version number in which this entity was obsoleted, and therefore
2301  * is no longer available.
2302  */
2304  /**
2305  * Whether the entity is unconditionally unavailable on this platform.
2306  */
2308  /**
2309  * An optional message to provide to a user of this API, e.g., to
2310  * suggest replacement APIs.
2311  */
2314 
2315 /**
2316  * Determine the availability of the entity that this cursor refers to
2317  * on any platforms for which availability information is known.
2318  *
2319  * \param cursor The cursor to query.
2320  *
2321  * \param always_deprecated If non-NULL, will be set to indicate whether the
2322  * entity is deprecated on all platforms.
2323  *
2324  * \param deprecated_message If non-NULL, will be set to the message text
2325  * provided along with the unconditional deprecation of this entity. The client
2326  * is responsible for deallocating this string.
2327  *
2328  * \param always_unavailable If non-NULL, will be set to indicate whether the
2329  * entity is unavailable on all platforms.
2330  *
2331  * \param unavailable_message If non-NULL, will be set to the message text
2332  * provided along with the unconditional unavailability of this entity. The
2333  * client is responsible for deallocating this string.
2334  *
2335  * \param availability If non-NULL, an array of CXPlatformAvailability instances
2336  * that will be populated with platform availability information, up to either
2337  * the number of platforms for which availability information is available (as
2338  * returned by this function) or \c availability_size, whichever is smaller.
2339  *
2340  * \param availability_size The number of elements available in the
2341  * \c availability array.
2342  *
2343  * \returns The number of platforms (N) for which availability information is
2344  * available (which is unrelated to \c availability_size).
2345  *
2346  * Note that the client is responsible for calling
2347  * \c clang_disposeCXPlatformAvailability to free each of the
2348  * platform-availability structures returned. There are
2349  * \c min(N, availability_size) such structures.
2350  */
2352  CXCursor cursor, int *always_deprecated, CXString *deprecated_message,
2353  int *always_unavailable, CXString *unavailable_message,
2354  CXPlatformAvailability *availability, int availability_size);
2355 
2356 /**
2357  * Free the memory associated with a \c CXPlatformAvailability structure.
2358  */
2359 CINDEX_LINKAGE void
2361 
2362 /**
2363  * If cursor refers to a variable declaration and it has initializer returns
2364  * cursor referring to the initializer otherwise return null cursor.
2365  */
2367 
2368 /**
2369  * If cursor refers to a variable declaration that has global storage returns 1.
2370  * If cursor refers to a variable declaration that doesn't have global storage
2371  * returns 0. Otherwise returns -1.
2372  */
2374 
2375 /**
2376  * If cursor refers to a variable declaration that has external storage
2377  * returns 1. If cursor refers to a variable declaration that doesn't have
2378  * external storage returns 0. Otherwise returns -1.
2379  */
2381 
2382 /**
2383  * Describe the "language" of the entity referred to by a cursor.
2384  */
2390 };
2391 
2392 /**
2393  * Determine the "language" of the entity referred to by a given cursor.
2394  */
2396 
2397 /**
2398  * Describe the "thread-local storage (TLS) kind" of the declaration
2399  * referred to by a cursor.
2400  */
2402 
2403 /**
2404  * Determine the "thread-local storage (TLS) kind" of the declaration
2405  * referred to by a cursor.
2406  */
2408 
2409 /**
2410  * Returns the translation unit that a cursor originated from.
2411  */
2413 
2414 /**
2415  * A fast container representing a set of CXCursors.
2416  */
2417 typedef struct CXCursorSetImpl *CXCursorSet;
2418 
2419 /**
2420  * Creates an empty CXCursorSet.
2421  */
2423 
2424 /**
2425  * Disposes a CXCursorSet and releases its associated memory.
2426  */
2428 
2429 /**
2430  * Queries a CXCursorSet to see if it contains a specific CXCursor.
2431  *
2432  * \returns non-zero if the set contains the specified cursor.
2433  */
2435  CXCursor cursor);
2436 
2437 /**
2438  * Inserts a CXCursor into a CXCursorSet.
2439  *
2440  * \returns zero if the CXCursor was already in the set, and non-zero otherwise.
2441  */
2443  CXCursor cursor);
2444 
2445 /**
2446  * Determine the semantic parent of the given cursor.
2447  *
2448  * The semantic parent of a cursor is the cursor that semantically contains
2449  * the given \p cursor. For many declarations, the lexical and semantic parents
2450  * are equivalent (the lexical parent is returned by
2451  * \c clang_getCursorLexicalParent()). They diverge when declarations or
2452  * definitions are provided out-of-line. For example:
2453  *
2454  * \code
2455  * class C {
2456  * void f();
2457  * };
2458  *
2459  * void C::f() { }
2460  * \endcode
2461  *
2462  * In the out-of-line definition of \c C::f, the semantic parent is
2463  * the class \c C, of which this function is a member. The lexical parent is
2464  * the place where the declaration actually occurs in the source code; in this
2465  * case, the definition occurs in the translation unit. In general, the
2466  * lexical parent for a given entity can change without affecting the semantics
2467  * of the program, and the lexical parent of different declarations of the
2468  * same entity may be different. Changing the semantic parent of a declaration,
2469  * on the other hand, can have a major impact on semantics, and redeclarations
2470  * of a particular entity should all have the same semantic context.
2471  *
2472  * In the example above, both declarations of \c C::f have \c C as their
2473  * semantic context, while the lexical context of the first \c C::f is \c C
2474  * and the lexical context of the second \c C::f is the translation unit.
2475  *
2476  * For global declarations, the semantic parent is the translation unit.
2477  */
2479 
2480 /**
2481  * Determine the lexical parent of the given cursor.
2482  *
2483  * The lexical parent of a cursor is the cursor in which the given \p cursor
2484  * was actually written. For many declarations, the lexical and semantic parents
2485  * are equivalent (the semantic parent is returned by
2486  * \c clang_getCursorSemanticParent()). They diverge when declarations or
2487  * definitions are provided out-of-line. For example:
2488  *
2489  * \code
2490  * class C {
2491  * void f();
2492  * };
2493  *
2494  * void C::f() { }
2495  * \endcode
2496  *
2497  * In the out-of-line definition of \c C::f, the semantic parent is
2498  * the class \c C, of which this function is a member. The lexical parent is
2499  * the place where the declaration actually occurs in the source code; in this
2500  * case, the definition occurs in the translation unit. In general, the
2501  * lexical parent for a given entity can change without affecting the semantics
2502  * of the program, and the lexical parent of different declarations of the
2503  * same entity may be different. Changing the semantic parent of a declaration,
2504  * on the other hand, can have a major impact on semantics, and redeclarations
2505  * of a particular entity should all have the same semantic context.
2506  *
2507  * In the example above, both declarations of \c C::f have \c C as their
2508  * semantic context, while the lexical context of the first \c C::f is \c C
2509  * and the lexical context of the second \c C::f is the translation unit.
2510  *
2511  * For declarations written in the global scope, the lexical parent is
2512  * the translation unit.
2513  */
2515 
2516 /**
2517  * Determine the set of methods that are overridden by the given
2518  * method.
2519  *
2520  * In both Objective-C and C++, a method (aka virtual member function,
2521  * in C++) can override a virtual method in a base class. For
2522  * Objective-C, a method is said to override any method in the class's
2523  * base class, its protocols, or its categories' protocols, that has the same
2524  * selector and is of the same kind (class or instance).
2525  * If no such method exists, the search continues to the class's superclass,
2526  * its protocols, and its categories, and so on. A method from an Objective-C
2527  * implementation is considered to override the same methods as its
2528  * corresponding method in the interface.
2529  *
2530  * For C++, a virtual member function overrides any virtual member
2531  * function with the same signature that occurs in its base
2532  * classes. With multiple inheritance, a virtual member function can
2533  * override several virtual member functions coming from different
2534  * base classes.
2535  *
2536  * In all cases, this function determines the immediate overridden
2537  * method, rather than all of the overridden methods. For example, if
2538  * a method is originally declared in a class A, then overridden in B
2539  * (which in inherits from A) and also in C (which inherited from B),
2540  * then the only overridden method returned from this function when
2541  * invoked on C's method will be B's method. The client may then
2542  * invoke this function again, given the previously-found overridden
2543  * methods, to map out the complete method-override set.
2544  *
2545  * \param cursor A cursor representing an Objective-C or C++
2546  * method. This routine will compute the set of methods that this
2547  * method overrides.
2548  *
2549  * \param overridden A pointer whose pointee will be replaced with a
2550  * pointer to an array of cursors, representing the set of overridden
2551  * methods. If there are no overridden methods, the pointee will be
2552  * set to NULL. The pointee must be freed via a call to
2553  * \c clang_disposeOverriddenCursors().
2554  *
2555  * \param num_overridden A pointer to the number of overridden
2556  * functions, will be set to the number of overridden functions in the
2557  * array pointed to by \p overridden.
2558  */
2560  CXCursor **overridden,
2561  unsigned *num_overridden);
2562 
2563 /**
2564  * Free the set of overridden cursors returned by \c
2565  * clang_getOverriddenCursors().
2566  */
2568 
2569 /**
2570  * Retrieve the file that is included by the given inclusion directive
2571  * cursor.
2572  */
2574 
2575 /**
2576  * @}
2577  */
2578 
2579 /**
2580  * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code
2581  *
2582  * Cursors represent a location within the Abstract Syntax Tree (AST). These
2583  * routines help map between cursors and the physical locations where the
2584  * described entities occur in the source code. The mapping is provided in
2585  * both directions, so one can map from source code to the AST and back.
2586  *
2587  * @{
2588  */
2589 
2590 /**
2591  * Map a source location to the cursor that describes the entity at that
2592  * location in the source code.
2593  *
2594  * clang_getCursor() maps an arbitrary source location within a translation
2595  * unit down to the most specific cursor that describes the entity at that
2596  * location. For example, given an expression \c x + y, invoking
2597  * clang_getCursor() with a source location pointing to "x" will return the
2598  * cursor for "x"; similarly for "y". If the cursor points anywhere between
2599  * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor()
2600  * will return a cursor referring to the "+" expression.
2601  *
2602  * \returns a cursor representing the entity at the given source location, or
2603  * a NULL cursor if no such entity can be found.
2604  */
2606 
2607 /**
2608  * Retrieve the physical location of the source constructor referenced
2609  * by the given cursor.
2610  *
2611  * The location of a declaration is typically the location of the name of that
2612  * declaration, where the name of that declaration would occur if it is
2613  * unnamed, or some keyword that introduces that particular declaration.
2614  * The location of a reference is where that reference occurs within the
2615  * source code.
2616  */
2618 
2619 /**
2620  * Retrieve the physical extent of the source construct referenced by
2621  * the given cursor.
2622  *
2623  * The extent of a cursor starts with the file/line/column pointing at the
2624  * first character within the source construct that the cursor refers to and
2625  * ends with the last character within that source construct. For a
2626  * declaration, the extent covers the declaration itself. For a reference,
2627  * the extent covers the location of the reference (e.g., where the referenced
2628  * entity was actually used).
2629  */
2631 
2632 /**
2633  * @}
2634  */
2635 
2636 /**
2637  * \defgroup CINDEX_TYPES Type information for CXCursors
2638  *
2639  * @{
2640  */
2641 
2642 /**
2643  * Describes the kind of type
2644  */
2646  /**
2647  * Represents an invalid type (e.g., where no type is available).
2648  */
2650 
2651  /**
2652  * A type whose specific kind is not exposed via this
2653  * interface.
2654  */
2656 
2657  /* Builtin types */
2699 
2719 
2720  /**
2721  * Represents a type that was referred to using an elaborated type keyword.
2722  *
2723  * E.g., struct S, or via a qualified name, e.g., N::M::type, or both.
2724  */
2726 
2727  /* OpenCL PipeType. */
2729 
2730  /* OpenCL builtin types. */
2771 
2775 
2787 
2789 
2793 };
2794 
2795 /**
2796  * Describes the calling convention of a function type
2797  */
2810  /* Alias for compatibility with older versions of API. */
2820 
2823 };
2824 
2825 /**
2826  * The type of an element in the abstract syntax tree.
2827  *
2828  */
2829 typedef struct {
2831  void *data[2];
2832 } CXType;
2833 
2834 /**
2835  * Retrieve the type of a CXCursor (if any).
2836  */
2838 
2839 /**
2840  * Pretty-print the underlying type using the rules of the
2841  * language of the translation unit from which it came.
2842  *
2843  * If the type is invalid, an empty string is returned.
2844  */
2846 
2847 /**
2848  * Retrieve the underlying type of a typedef declaration.
2849  *
2850  * If the cursor does not reference a typedef declaration, an invalid type is
2851  * returned.
2852  */
2854 
2855 /**
2856  * Retrieve the integer type of an enum declaration.
2857  *
2858  * If the cursor does not reference an enum declaration, an invalid type is
2859  * returned.
2860  */
2862 
2863 /**
2864  * Retrieve the integer value of an enum constant declaration as a signed
2865  * long long.
2866  *
2867  * If the cursor does not reference an enum constant declaration, LLONG_MIN is
2868  * returned. Since this is also potentially a valid constant value, the kind of
2869  * the cursor must be verified before calling this function.
2870  */
2872 
2873 /**
2874  * Retrieve the integer value of an enum constant declaration as an unsigned
2875  * long long.
2876  *
2877  * If the cursor does not reference an enum constant declaration, ULLONG_MAX is
2878  * returned. Since this is also potentially a valid constant value, the kind of
2879  * the cursor must be verified before calling this function.
2880  */
2881 CINDEX_LINKAGE unsigned long long
2883 
2884 /**
2885  * Retrieve the bit width of a bit field declaration as an integer.
2886  *
2887  * If a cursor that is not a bit field declaration is passed in, -1 is returned.
2888  */
2890 
2891 /**
2892  * Retrieve the number of non-variadic arguments associated with a given
2893  * cursor.
2894  *
2895  * The number of arguments can be determined for calls as well as for
2896  * declarations of functions or methods. For other cursors -1 is returned.
2897  */
2899 
2900 /**
2901  * Retrieve the argument cursor of a function or method.
2902  *
2903  * The argument cursor can be determined for calls as well as for declarations
2904  * of functions or methods. For other cursors and for invalid indices, an
2905  * invalid cursor is returned.
2906  */
2908 
2909 /**
2910  * Describes the kind of a template argument.
2911  *
2912  * See the definition of llvm::clang::TemplateArgument::ArgKind for full
2913  * element descriptions.
2914  */
2925  /* Indicates an error case, preventing the kind from being deduced. */
2927 };
2928 
2929 /**
2930  * Returns the number of template args of a function, struct, or class decl
2931  * representing a template specialization.
2932  *
2933  * If the argument cursor cannot be converted into a template function
2934  * declaration, -1 is returned.
2935  *
2936  * For example, for the following declaration and specialization:
2937  * template <typename T, int kInt, bool kBool>
2938  * void foo() { ... }
2939  *
2940  * template <>
2941  * void foo<float, -7, true>();
2942  *
2943  * The value 3 would be returned from this call.
2944  */
2946 
2947 /**
2948  * Retrieve the kind of the I'th template argument of the CXCursor C.
2949  *
2950  * If the argument CXCursor does not represent a FunctionDecl, StructDecl, or
2951  * ClassTemplatePartialSpecialization, an invalid template argument kind is
2952  * returned.
2953  *
2954  * For example, for the following declaration and specialization:
2955  * template <typename T, int kInt, bool kBool>
2956  * void foo() { ... }
2957  *
2958  * template <>
2959  * void foo<float, -7, true>();
2960  *
2961  * For I = 0, 1, and 2, Type, Integral, and Integral will be returned,
2962  * respectively.
2963  */
2966 
2967 /**
2968  * Retrieve a CXType representing the type of a TemplateArgument of a
2969  * function decl representing a template specialization.
2970  *
2971  * If the argument CXCursor does not represent a FunctionDecl, StructDecl,
2972  * ClassDecl or ClassTemplatePartialSpecialization whose I'th template argument
2973  * has a kind of CXTemplateArgKind_Integral, an invalid type is returned.
2974  *
2975  * For example, for the following declaration and specialization:
2976  * template <typename T, int kInt, bool kBool>
2977  * void foo() { ... }
2978  *
2979  * template <>
2980  * void foo<float, -7, true>();
2981  *
2982  * If called with I = 0, "float", will be returned.
2983  * Invalid types will be returned for I == 1 or 2.
2984  */
2986  unsigned I);
2987 
2988 /**
2989  * Retrieve the value of an Integral TemplateArgument (of a function
2990  * decl representing a template specialization) as a signed long long.
2991  *
2992  * It is undefined to call this function on a CXCursor that does not represent a
2993  * FunctionDecl, StructDecl, ClassDecl or ClassTemplatePartialSpecialization
2994  * whose I'th template argument is not an integral value.
2995  *
2996  * For example, for the following declaration and specialization:
2997  * template <typename T, int kInt, bool kBool>
2998  * void foo() { ... }
2999  *
3000  * template <>
3001  * void foo<float, -7, true>();
3002  *
3003  * If called with I = 1 or 2, -7 or true will be returned, respectively.
3004  * For I == 0, this function's behavior is undefined.
3005  */
3007  unsigned I);
3008 
3009 /**
3010  * Retrieve the value of an Integral TemplateArgument (of a function
3011  * decl representing a template specialization) as an unsigned long long.
3012  *
3013  * It is undefined to call this function on a CXCursor that does not represent a
3014  * FunctionDecl, StructDecl, ClassDecl or ClassTemplatePartialSpecialization or
3015  * whose I'th template argument is not an integral value.
3016  *
3017  * For example, for the following declaration and specialization:
3018  * template <typename T, int kInt, bool kBool>
3019  * void foo() { ... }
3020  *
3021  * template <>
3022  * void foo<float, 2147483649, true>();
3023  *
3024  * If called with I = 1 or 2, 2147483649 or true will be returned, respectively.
3025  * For I == 0, this function's behavior is undefined.
3026  */
3027 CINDEX_LINKAGE unsigned long long
3029 
3030 /**
3031  * Determine whether two CXTypes represent the same type.
3032  *
3033  * \returns non-zero if the CXTypes represent the same type and
3034  * zero otherwise.
3035  */
3037 
3038 /**
3039  * Return the canonical type for a CXType.
3040  *
3041  * Clang's type system explicitly models typedefs and all the ways
3042  * a specific type can be represented. The canonical type is the underlying
3043  * type with all the "sugar" removed. For example, if 'T' is a typedef
3044  * for 'int', the canonical type for 'T' would be 'int'.
3045  */
3047 
3048 /**
3049  * Determine whether a CXType has the "const" qualifier set,
3050  * without looking through typedefs that may have added "const" at a
3051  * different level.
3052  */
3054 
3055 /**
3056  * Determine whether a CXCursor that is a macro, is
3057  * function like.
3058  */
3060 
3061 /**
3062  * Determine whether a CXCursor that is a macro, is a
3063  * builtin one.
3064  */
3066 
3067 /**
3068  * Determine whether a CXCursor that is a function declaration, is an
3069  * inline declaration.
3070  */
3072 
3073 /**
3074  * Determine whether a CXType has the "volatile" qualifier set,
3075  * without looking through typedefs that may have added "volatile" at
3076  * a different level.
3077  */
3079 
3080 /**
3081  * Determine whether a CXType has the "restrict" qualifier set,
3082  * without looking through typedefs that may have added "restrict" at a
3083  * different level.
3084  */
3086 
3087 /**
3088  * Returns the address space of the given type.
3089  */
3091 
3092 /**
3093  * Returns the typedef name of the given type.
3094  */
3096 
3097 /**
3098  * For pointer types, returns the type of the pointee.
3099  */
3101 
3102 /**
3103  * Retrieve the unqualified variant of the given type, removing as
3104  * little sugar as possible.
3105  *
3106  * For example, given the following series of typedefs:
3107  *
3108  * \code
3109  * typedef int Integer;
3110  * typedef const Integer CInteger;
3111  * typedef CInteger DifferenceType;
3112  * \endcode
3113  *
3114  * Executing \c clang_getUnqualifiedType() on a \c CXType that
3115  * represents \c DifferenceType, will desugar to a type representing
3116  * \c Integer, that has no qualifiers.
3117  *
3118  * And, executing \c clang_getUnqualifiedType() on the type of the
3119  * first argument of the following function declaration:
3120  *
3121  * \code
3122  * void foo(const int);
3123  * \endcode
3124  *
3125  * Will return a type representing \c int, removing the \c const
3126  * qualifier.
3127  *
3128  * Sugar over array types is not desugared.
3129  *
3130  * A type can be checked for qualifiers with \c
3131  * clang_isConstQualifiedType(), \c clang_isVolatileQualifiedType()
3132  * and \c clang_isRestrictQualifiedType().
3133  *
3134  * A type that resulted from a call to \c clang_getUnqualifiedType
3135  * will return \c false for all of the above calls.
3136  */
3138 
3139 /**
3140  * For reference types (e.g., "const int&"), returns the type that the
3141  * reference refers to (e.g "const int").
3142  *
3143  * Otherwise, returns the type itself.
3144  *
3145  * A type that has kind \c CXType_LValueReference or
3146  * \c CXType_RValueReference is a reference type.
3147  */
3149 
3150 /**
3151  * Return the cursor for the declaration of the given type.
3152  */
3154 
3155 /**
3156  * Returns the Objective-C type encoding for the specified declaration.
3157  */
3159 
3160 /**
3161  * Returns the Objective-C type encoding for the specified CXType.
3162  */
3164 
3165 /**
3166  * Retrieve the spelling of a given CXTypeKind.
3167  */
3169 
3170 /**
3171  * Retrieve the calling convention associated with a function type.
3172  *
3173  * If a non-function type is passed in, CXCallingConv_Invalid is returned.
3174  */
3176 
3177 /**
3178  * Retrieve the return type associated with a function type.
3179  *
3180  * If a non-function type is passed in, an invalid type is returned.
3181  */
3183 
3184 /**
3185  * Retrieve the exception specification type associated with a function type.
3186  * This is a value of type CXCursor_ExceptionSpecificationKind.
3187  *
3188  * If a non-function type is passed in, an error code of -1 is returned.
3189  */
3191 
3192 /**
3193  * Retrieve the number of non-variadic parameters associated with a
3194  * function type.
3195  *
3196  * If a non-function type is passed in, -1 is returned.
3197  */
3199 
3200 /**
3201  * Retrieve the type of a parameter of a function type.
3202  *
3203  * If a non-function type is passed in or the function does not have enough
3204  * parameters, an invalid type is returned.
3205  */
3207 
3208 /**
3209  * Retrieves the base type of the ObjCObjectType.
3210  *
3211  * If the type is not an ObjC object, an invalid type is returned.
3212  */
3214 
3215 /**
3216  * Retrieve the number of protocol references associated with an ObjC object/id.
3217  *
3218  * If the type is not an ObjC object, 0 is returned.
3219  */
3221 
3222 /**
3223  * Retrieve the decl for a protocol reference for an ObjC object/id.
3224  *
3225  * If the type is not an ObjC object or there are not enough protocol
3226  * references, an invalid cursor is returned.
3227  */
3229 
3230 /**
3231  * Retrieve the number of type arguments associated with an ObjC object.
3232  *
3233  * If the type is not an ObjC object, 0 is returned.
3234  */
3236 
3237 /**
3238  * Retrieve a type argument associated with an ObjC object.
3239  *
3240  * If the type is not an ObjC or the index is not valid,
3241  * an invalid type is returned.
3242  */
3244 
3245 /**
3246  * Return 1 if the CXType is a variadic function type, and 0 otherwise.
3247  */
3249 
3250 /**
3251  * Retrieve the return type associated with a given cursor.
3252  *
3253  * This only returns a valid type if the cursor refers to a function or method.
3254  */
3256 
3257 /**
3258  * Retrieve the exception specification type associated with a given cursor.
3259  * This is a value of type CXCursor_ExceptionSpecificationKind.
3260  *
3261  * This only returns a valid result if the cursor refers to a function or
3262  * method.
3263  */
3265 
3266 /**
3267  * Return 1 if the CXType is a POD (plain old data) type, and 0
3268  * otherwise.
3269  */
3271 
3272 /**
3273  * Return the element type of an array, complex, or vector type.
3274  *
3275  * If a type is passed in that is not an array, complex, or vector type,
3276  * an invalid type is returned.
3277  */
3279 
3280 /**
3281  * Return the number of elements of an array or vector type.
3282  *
3283  * If a type is passed in that is not an array or vector type,
3284  * -1 is returned.
3285  */
3287 
3288 /**
3289  * Return the element type of an array type.
3290  *
3291  * If a non-array type is passed in, an invalid type is returned.
3292  */
3294 
3295 /**
3296  * Return the array size of a constant array.
3297  *
3298  * If a non-array type is passed in, -1 is returned.
3299  */
3301 
3302 /**
3303  * Retrieve the type named by the qualified-id.
3304  *
3305  * If a non-elaborated type is passed in, an invalid type is returned.
3306  */
3308 
3309 /**
3310  * Determine if a typedef is 'transparent' tag.
3311  *
3312  * A typedef is considered 'transparent' if it shares a name and spelling
3313  * location with its underlying tag type, as is the case with the NS_ENUM macro.
3314  *
3315  * \returns non-zero if transparent and zero otherwise.
3316  */
3318 
3320  /**
3321  * Values of this type can never be null.
3322  */
3324  /**
3325  * Values of this type can be null.
3326  */
3328  /**
3329  * Whether values of this type can be null is (explicitly)
3330  * unspecified. This captures a (fairly rare) case where we
3331  * can't conclude anything about the nullability of the type even
3332  * though it has been considered.
3333  */
3335  /**
3336  * Nullability is not applicable to this type.
3337  */
3339 
3340  /**
3341  * Generally behaves like Nullable, except when used in a block parameter that
3342  * was imported into a swift async method. There, swift will assume that the
3343  * parameter can get null even if no error occurred. _Nullable parameters are
3344  * assumed to only get null on error.
3345  */
3347 };
3348 
3349 /**
3350  * Retrieve the nullability kind of a pointer type.
3351  */
3353 
3354 /**
3355  * List the possible error codes for \c clang_Type_getSizeOf,
3356  * \c clang_Type_getAlignOf, \c clang_Type_getOffsetOf and
3357  * \c clang_Cursor_getOffsetOf.
3358  *
3359  * A value of this enumeration type can be returned if the target type is not
3360  * a valid argument to sizeof, alignof or offsetof.
3361  */
3363  /**
3364  * Type is of kind CXType_Invalid.
3365  */
3367  /**
3368  * The type is an incomplete Type.
3369  */
3371  /**
3372  * The type is a dependent Type.
3373  */
3375  /**
3376  * The type is not a constant size type.
3377  */
3379  /**
3380  * The Field name is not valid for this record.
3381  */
3383  /**
3384  * The type is undeduced.
3385  */
3387 };
3388 
3389 /**
3390  * Return the alignment of a type in bytes as per C++[expr.alignof]
3391  * standard.
3392  *
3393  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3394  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3395  * is returned.
3396  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3397  * returned.
3398  * If the type declaration is not a constant size type,
3399  * CXTypeLayoutError_NotConstantSize is returned.
3400  */
3402 
3403 /**
3404  * Return the class type of an member pointer type.
3405  *
3406  * If a non-member-pointer type is passed in, an invalid type is returned.
3407  */
3409 
3410 /**
3411  * Return the size of a type in bytes as per C++[expr.sizeof] standard.
3412  *
3413  * If the type declaration is invalid, CXTypeLayoutError_Invalid is returned.
3414  * If the type declaration is an incomplete type, CXTypeLayoutError_Incomplete
3415  * is returned.
3416  * If the type declaration is a dependent type, CXTypeLayoutError_Dependent is
3417  * returned.
3418  */
3420 
3421 /**
3422  * Return the offset of a field named S in a record of type T in bits
3423  * as it would be returned by __offsetof__ as per C++11[18.2p4]
3424  *
3425  * If the cursor is not a record field declaration, CXTypeLayoutError_Invalid
3426  * is returned.
3427  * If the field's type declaration is an incomplete type,
3428  * CXTypeLayoutError_Incomplete is returned.
3429  * If the field's type declaration is a dependent type,
3430  * CXTypeLayoutError_Dependent is returned.
3431  * If the field's name S is not found,
3432  * CXTypeLayoutError_InvalidFieldName is returned.
3433  */
3434 CINDEX_LINKAGE long long clang_Type_getOffsetOf(CXType T, const char *S);
3435 
3436 /**
3437  * Return the type that was modified by this attributed type.
3438  *
3439  * If the type is not an attributed type, an invalid type is returned.
3440  */
3442 
3443 /**
3444  * Gets the type contained by this atomic type.
3445  *
3446  * If a non-atomic type is passed in, an invalid type is returned.
3447  */
3449 
3450 /**
3451  * Return the offset of the field represented by the Cursor.
3452  *
3453  * If the cursor is not a field declaration, -1 is returned.
3454  * If the cursor semantic parent is not a record field declaration,
3455  * CXTypeLayoutError_Invalid is returned.
3456  * If the field's type declaration is an incomplete type,
3457  * CXTypeLayoutError_Incomplete is returned.
3458  * If the field's type declaration is a dependent type,
3459  * CXTypeLayoutError_Dependent is returned.
3460  * If the field's name S is not found,
3461  * CXTypeLayoutError_InvalidFieldName is returned.
3462  */
3464 
3465 /**
3466  * Determine whether the given cursor represents an anonymous
3467  * tag or namespace
3468  */
3470 
3471 /**
3472  * Determine whether the given cursor represents an anonymous record
3473  * declaration.
3474  */
3476 
3477 /**
3478  * Determine whether the given cursor represents an inline namespace
3479  * declaration.
3480  */
3482 
3484  /** No ref-qualifier was provided. */
3486  /** An lvalue ref-qualifier was provided (\c &). */
3488  /** An rvalue ref-qualifier was provided (\c &&). */
3490 };
3491 
3492 /**
3493  * Returns the number of template arguments for given template
3494  * specialization, or -1 if type \c T is not a template specialization.
3495  */
3497 
3498 /**
3499  * Returns the type template argument of a template class specialization
3500  * at given index.
3501  *
3502  * This function only returns template type arguments and does not handle
3503  * template template arguments or variadic packs.
3504  */
3506  unsigned i);
3507 
3508 /**
3509  * Retrieve the ref-qualifier kind of a function or method.
3510  *
3511  * The ref-qualifier is returned for C++ functions or methods. For other types
3512  * or non-C++ declarations, CXRefQualifier_None is returned.
3513  */
3515 
3516 /**
3517  * Returns non-zero if the cursor specifies a Record member that is a
3518  * bitfield.
3519  */
3521 
3522 /**
3523  * Returns 1 if the base class specified by the cursor with kind
3524  * CX_CXXBaseSpecifier is virtual.
3525  */
3527 
3528 /**
3529  * Represents the C++ access control level to a base class for a
3530  * cursor with kind CX_CXXBaseSpecifier.
3531  */
3537 };
3538 
3539 /**
3540  * Returns the access control level for the referenced object.
3541  *
3542  * If the cursor refers to a C++ declaration, its access control level within
3543  * its parent scope is returned. Otherwise, if the cursor refers to a base
3544  * specifier or access specifier, the specifier itself is returned.
3545  */
3547 
3548 /**
3549  * Represents the storage classes as declared in the source. CX_SC_Invalid
3550  * was added for the case that the passed cursor in not a declaration.
3551  */
3561 };
3562 
3563 /**
3564  * Returns the storage class for a function or variable declaration.
3565  *
3566  * If the passed in Cursor is not a function or variable declaration,
3567  * CX_SC_Invalid is returned else the storage class.
3568  */
3570 
3571 /**
3572  * Determine the number of overloaded declarations referenced by a
3573  * \c CXCursor_OverloadedDeclRef cursor.
3574  *
3575  * \param cursor The cursor whose overloaded declarations are being queried.
3576  *
3577  * \returns The number of overloaded declarations referenced by \c cursor. If it
3578  * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0.
3579  */
3581 
3582 /**
3583  * Retrieve a cursor for one of the overloaded declarations referenced
3584  * by a \c CXCursor_OverloadedDeclRef cursor.
3585  *
3586  * \param cursor The cursor whose overloaded declarations are being queried.
3587  *
3588  * \param index The zero-based index into the set of overloaded declarations in
3589  * the cursor.
3590  *
3591  * \returns A cursor representing the declaration referenced by the given
3592  * \c cursor at the specified \c index. If the cursor does not have an
3593  * associated set of overloaded declarations, or if the index is out of bounds,
3594  * returns \c clang_getNullCursor();
3595  */
3597  unsigned index);
3598 
3599 /**
3600  * @}
3601  */
3602 
3603 /**
3604  * \defgroup CINDEX_ATTRIBUTES Information for attributes
3605  *
3606  * @{
3607  */
3608 
3609 /**
3610  * For cursors representing an iboutletcollection attribute,
3611  * this function returns the collection element type.
3612  *
3613  */
3615 
3616 /**
3617  * @}
3618  */
3619 
3620 /**
3621  * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors
3622  *
3623  * These routines provide the ability to traverse the abstract syntax tree
3624  * using cursors.
3625  *
3626  * @{
3627  */
3628 
3629 /**
3630  * Describes how the traversal of the children of a particular
3631  * cursor should proceed after visiting a particular child cursor.
3632  *
3633  * A value of this enumeration type should be returned by each
3634  * \c CXCursorVisitor to indicate how clang_visitChildren() proceed.
3635  */
3637  /**
3638  * Terminates the cursor traversal.
3639  */
3641  /**
3642  * Continues the cursor traversal with the next sibling of
3643  * the cursor just visited, without visiting its children.
3644  */
3646  /**
3647  * Recursively traverse the children of this cursor, using
3648  * the same visitor and client data.
3649  */
3651 };
3652 
3653 /**
3654  * Visitor invoked for each cursor found by a traversal.
3655  *
3656  * This visitor function will be invoked for each cursor found by
3657  * clang_visitCursorChildren(). Its first argument is the cursor being
3658  * visited, its second argument is the parent visitor for that cursor,
3659  * and its third argument is the client data provided to
3660  * clang_visitCursorChildren().
3661  *
3662  * The visitor should return one of the \c CXChildVisitResult values
3663  * to direct clang_visitCursorChildren().
3664  */
3666  CXCursor parent,
3667  CXClientData client_data);
3668 
3669 /**
3670  * Visit the children of a particular cursor.
3671  *
3672  * This function visits all the direct children of the given cursor,
3673  * invoking the given \p visitor function with the cursors of each
3674  * visited child. The traversal may be recursive, if the visitor returns
3675  * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if
3676  * the visitor returns \c CXChildVisit_Break.
3677  *
3678  * \param parent the cursor whose child may be visited. All kinds of
3679  * cursors can be visited, including invalid cursors (which, by
3680  * definition, have no children).
3681  *
3682  * \param visitor the visitor function that will be invoked for each
3683  * child of \p parent.
3684  *
3685  * \param client_data pointer data supplied by the client, which will
3686  * be passed to the visitor each time it is invoked.
3687  *
3688  * \returns a non-zero value if the traversal was terminated
3689  * prematurely by the visitor returning \c CXChildVisit_Break.
3690  */
3692  CXCursorVisitor visitor,
3693  CXClientData client_data);
3694 #ifdef __has_feature
3695 #if __has_feature(blocks)
3696 /**
3697  * Visitor invoked for each cursor found by a traversal.
3698  *
3699  * This visitor block will be invoked for each cursor found by
3700  * clang_visitChildrenWithBlock(). Its first argument is the cursor being
3701  * visited, its second argument is the parent visitor for that cursor.
3702  *
3703  * The visitor should return one of the \c CXChildVisitResult values
3704  * to direct clang_visitChildrenWithBlock().
3705  */
3706 typedef enum CXChildVisitResult (^CXCursorVisitorBlock)(CXCursor cursor,
3707  CXCursor parent);
3708 
3709 /**
3710  * Visits the children of a cursor using the specified block. Behaves
3711  * identically to clang_visitChildren() in all other respects.
3712  */
3713 CINDEX_LINKAGE unsigned
3714 clang_visitChildrenWithBlock(CXCursor parent, CXCursorVisitorBlock block);
3715 #endif
3716 #endif
3717 
3718 /**
3719  * @}
3720  */
3721 
3722 /**
3723  * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST
3724  *
3725  * These routines provide the ability to determine references within and
3726  * across translation units, by providing the names of the entities referenced
3727  * by cursors, follow reference cursors to the declarations they reference,
3728  * and associate declarations with their definitions.
3729  *
3730  * @{
3731  */
3732 
3733 /**
3734  * Retrieve a Unified Symbol Resolution (USR) for the entity referenced
3735  * by the given cursor.
3736  *
3737  * A Unified Symbol Resolution (USR) is a string that identifies a particular
3738  * entity (function, class, variable, etc.) within a program. USRs can be
3739  * compared across translation units to determine, e.g., when references in
3740  * one translation refer to an entity defined in another translation unit.
3741  */
3743 
3744 /**
3745  * Construct a USR for a specified Objective-C class.
3746  */
3747 CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name);
3748 
3749 /**
3750  * Construct a USR for a specified Objective-C category.
3751  */
3753  const char *class_name, const char *category_name);
3754 
3755 /**
3756  * Construct a USR for a specified Objective-C protocol.
3757  */
3759 clang_constructUSR_ObjCProtocol(const char *protocol_name);
3760 
3761 /**
3762  * Construct a USR for a specified Objective-C instance variable and
3763  * the USR for its containing class.
3764  */
3766  CXString classUSR);
3767 
3768 /**
3769  * Construct a USR for a specified Objective-C method and
3770  * the USR for its containing class.
3771  */
3773  unsigned isInstanceMethod,
3774  CXString classUSR);
3775 
3776 /**
3777  * Construct a USR for a specified Objective-C property and the USR
3778  * for its containing class.
3779  */
3781  CXString classUSR);
3782 
3783 /**
3784  * Retrieve a name for the entity referenced by this cursor.
3785  */
3787 
3788 /**
3789  * Retrieve a range for a piece that forms the cursors spelling name.
3790  * Most of the times there is only one range for the complete spelling but for
3791  * Objective-C methods and Objective-C message expressions, there are multiple
3792  * pieces for each selector identifier.
3793  *
3794  * \param pieceIndex the index of the spelling name piece. If this is greater
3795  * than the actual number of pieces, it will return a NULL (invalid) range.
3796  *
3797  * \param options Reserved.
3798  */
3800  CXCursor, unsigned pieceIndex, unsigned options);
3801 
3802 /**
3803  * Opaque pointer representing a policy that controls pretty printing
3804  * for \c clang_getCursorPrettyPrinted.
3805  */
3806 typedef void *CXPrintingPolicy;
3807 
3808 /**
3809  * Properties for the printing policy.
3810  *
3811  * See \c clang::PrintingPolicy for more information.
3812  */
3840 
3842 };
3843 
3844 /**
3845  * Get a property value for the given printing policy.
3846  */
3847 CINDEX_LINKAGE unsigned
3849  enum CXPrintingPolicyProperty Property);
3850 
3851 /**
3852  * Set a property value for the given printing policy.
3853  */
3854 CINDEX_LINKAGE void
3856  enum CXPrintingPolicyProperty Property,
3857  unsigned Value);
3858 
3859 /**
3860  * Retrieve the default policy for the cursor.
3861  *
3862  * The policy should be released after use with \c
3863  * clang_PrintingPolicy_dispose.
3864  */
3866 
3867 /**
3868  * Release a printing policy.
3869  */
3871 
3872 /**
3873  * Pretty print declarations.
3874  *
3875  * \param Cursor The cursor representing a declaration.
3876  *
3877  * \param Policy The policy to control the entities being printed. If
3878  * NULL, a default policy is used.
3879  *
3880  * \returns The pretty printed declaration or the empty string for
3881  * other cursors.
3882  */
3885 
3886 /**
3887  * Retrieve the display name for the entity referenced by this cursor.
3888  *
3889  * The display name contains extra information that helps identify the cursor,
3890  * such as the parameters of a function or template or the arguments of a
3891  * class template specialization.
3892  */
3894 
3895 /** For a cursor that is a reference, retrieve a cursor representing the
3896  * entity that it references.
3897  *
3898  * Reference cursors refer to other entities in the AST. For example, an
3899  * Objective-C superclass reference cursor refers to an Objective-C class.
3900  * This function produces the cursor for the Objective-C class from the
3901  * cursor for the superclass reference. If the input cursor is a declaration or
3902  * definition, it returns that declaration or definition unchanged.
3903  * Otherwise, returns the NULL cursor.
3904  */
3906 
3907 /**
3908  * For a cursor that is either a reference to or a declaration
3909  * of some entity, retrieve a cursor that describes the definition of
3910  * that entity.
3911  *
3912  * Some entities can be declared multiple times within a translation
3913  * unit, but only one of those declarations can also be a
3914  * definition. For example, given:
3915  *
3916  * \code
3917  * int f(int, int);
3918  * int g(int x, int y) { return f(x, y); }
3919  * int f(int a, int b) { return a + b; }
3920  * int f(int, int);
3921  * \endcode
3922  *
3923  * there are three declarations of the function "f", but only the
3924  * second one is a definition. The clang_getCursorDefinition()
3925  * function will take any cursor pointing to a declaration of "f"
3926  * (the first or fourth lines of the example) or a cursor referenced
3927  * that uses "f" (the call to "f' inside "g") and will return a
3928  * declaration cursor pointing to the definition (the second "f"
3929  * declaration).
3930  *
3931  * If given a cursor for which there is no corresponding definition,
3932  * e.g., because there is no definition of that entity within this
3933  * translation unit, returns a NULL cursor.
3934  */
3936 
3937 /**
3938  * Determine whether the declaration pointed to by this cursor
3939  * is also a definition of that entity.
3940  */
3942 
3943 /**
3944  * Retrieve the canonical cursor corresponding to the given cursor.
3945  *
3946  * In the C family of languages, many kinds of entities can be declared several
3947  * times within a single translation unit. For example, a structure type can
3948  * be forward-declared (possibly multiple times) and later defined:
3949  *
3950  * \code
3951  * struct X;
3952  * struct X;
3953  * struct X {
3954  * int member;
3955  * };
3956  * \endcode
3957  *
3958  * The declarations and the definition of \c X are represented by three
3959  * different cursors, all of which are declarations of the same underlying
3960  * entity. One of these cursor is considered the "canonical" cursor, which
3961  * is effectively the representative for the underlying entity. One can
3962  * determine if two cursors are declarations of the same underlying entity by
3963  * comparing their canonical cursors.
3964  *
3965  * \returns The canonical cursor for the entity referred to by the given cursor.
3966  */
3968 
3969 /**
3970  * If the cursor points to a selector identifier in an Objective-C
3971  * method or message expression, this returns the selector index.
3972  *
3973  * After getting a cursor with #clang_getCursor, this can be called to
3974  * determine if the location points to a selector identifier.
3975  *
3976  * \returns The selector index if the cursor is an Objective-C method or message
3977  * expression and the cursor is pointing to a selector identifier, or -1
3978  * otherwise.
3979  */
3981 
3982 /**
3983  * Given a cursor pointing to a C++ method call or an Objective-C
3984  * message, returns non-zero if the method/message is "dynamic", meaning:
3985  *
3986  * For a C++ method: the call is virtual.
3987  * For an Objective-C message: the receiver is an object instance, not 'super'
3988  * or a specific class.
3989  *
3990  * If the method/message is "static" or the cursor does not point to a
3991  * method/message, it will return zero.
3992  */
3994 
3995 /**
3996  * Given a cursor pointing to an Objective-C message or property
3997  * reference, or C++ method call, returns the CXType of the receiver.
3998  */
4000 
4001 /**
4002  * Property attributes for a \c CXCursor_ObjCPropertyDecl.
4003  */
4004 typedef enum {
4020 
4021 /**
4022  * Given a cursor that represents a property declaration, return the
4023  * associated property attributes. The bits are formed from
4024  * \c CXObjCPropertyAttrKind.
4025  *
4026  * \param reserved Reserved for future use, pass 0.
4027  */
4028 CINDEX_LINKAGE unsigned
4030 
4031 /**
4032  * Given a cursor that represents a property declaration, return the
4033  * name of the method that implements the getter.
4034  */
4036 
4037 /**
4038  * Given a cursor that represents a property declaration, return the
4039  * name of the method that implements the setter, if any.
4040  */
4042 
4043 /**
4044  * 'Qualifiers' written next to the return and parameter types in
4045  * Objective-C method declarations.
4046  */
4047 typedef enum {
4056 
4057 /**
4058  * Given a cursor that represents an Objective-C method or parameter
4059  * declaration, return the associated Objective-C qualifiers for the return
4060  * type or the parameter respectively. The bits are formed from
4061  * CXObjCDeclQualifierKind.
4062  */
4064 
4065 /**
4066  * Given a cursor that represents an Objective-C method or property
4067  * declaration, return non-zero if the declaration was affected by "\@optional".
4068  * Returns zero if the cursor is not such a declaration or it is "\@required".
4069  */
4071 
4072 /**
4073  * Returns non-zero if the given cursor is a variadic function or method.
4074  */
4076 
4077 /**
4078  * Returns non-zero if the given cursor points to a symbol marked with
4079  * external_source_symbol attribute.
4080  *
4081  * \param language If non-NULL, and the attribute is present, will be set to
4082  * the 'language' string from the attribute.
4083  *
4084  * \param definedIn If non-NULL, and the attribute is present, will be set to
4085  * the 'definedIn' string from the attribute.
4086  *
4087  * \param isGenerated If non-NULL, and the attribute is present, will be set to
4088  * non-zero if the 'generated_declaration' is set in the attribute.
4089  */
4091  CXString *language,
4092  CXString *definedIn,
4093  unsigned *isGenerated);
4094 
4095 /**
4096  * Given a cursor that represents a declaration, return the associated
4097  * comment's source range. The range may include multiple consecutive comments
4098  * with whitespace in between.
4099  */
4101 
4102 /**
4103  * Given a cursor that represents a declaration, return the associated
4104  * comment text, including comment markers.
4105  */
4107 
4108 /**
4109  * Given a cursor that represents a documentable entity (e.g.,
4110  * declaration), return the associated \paragraph; otherwise return the
4111  * first paragraph.
4112  */
4114 
4115 /**
4116  * @}
4117  */
4118 
4119 /** \defgroup CINDEX_MANGLE Name Mangling API Functions
4120  *
4121  * @{
4122  */
4123 
4124 /**
4125  * Retrieve the CXString representing the mangled name of the cursor.
4126  */
4128 
4129 /**
4130  * Retrieve the CXStrings representing the mangled symbols of the C++
4131  * constructor or destructor at the cursor.
4132  */
4134 
4135 /**
4136  * Retrieve the CXStrings representing the mangled symbols of the ObjC
4137  * class interface or implementation at the cursor.
4138  */
4140 
4141 /**
4142  * @}
4143  */
4144 
4145 /**
4146  * \defgroup CINDEX_MODULE Module introspection
4147  *
4148  * The functions in this group provide access to information about modules.
4149  *
4150  * @{
4151  */
4152 
4153 typedef void *CXModule;
4154 
4155 /**
4156  * Given a CXCursor_ModuleImportDecl cursor, return the associated module.
4157  */
4159 
4160 /**
4161  * Given a CXFile header file, return the module that contains it, if one
4162  * exists.
4163  */
4165 
4166 /**
4167  * \param Module a module object.
4168  *
4169  * \returns the module file where the provided module object came from.
4170  */
4172 
4173 /**
4174  * \param Module a module object.
4175  *
4176  * \returns the parent of a sub-module or NULL if the given module is top-level,
4177  * e.g. for 'std.vector' it will return the 'std' module.
4178  */
4180 
4181 /**
4182  * \param Module a module object.
4183  *
4184  * \returns the name of the module, e.g. for the 'std.vector' sub-module it
4185  * will return "vector".
4186  */
4188 
4189 /**
4190  * \param Module a module object.
4191  *
4192  * \returns the full name of the module, e.g. "std.vector".
4193  */
4195 
4196 /**
4197  * \param Module a module object.
4198  *
4199  * \returns non-zero if the module is a system one.
4200  */
4202 
4203 /**
4204  * \param Module a module object.
4205  *
4206  * \returns the number of top level headers associated with this module.
4207  */
4209  CXModule Module);
4210 
4211 /**
4212  * \param Module a module object.
4213  *
4214  * \param Index top level header index (zero-based).
4215  *
4216  * \returns the specified top level header associated with the module.
4217  */
4220  unsigned Index);
4221 
4222 /**
4223  * @}
4224  */
4225 
4226 /**
4227  * \defgroup CINDEX_CPP C++ AST introspection
4228  *
4229  * The routines in this group provide access information in the ASTs specific
4230  * to C++ language features.
4231  *
4232  * @{
4233  */
4234 
4235 /**
4236  * Determine if a C++ constructor is a converting constructor.
4237  */
4238 CINDEX_LINKAGE unsigned
4240 
4241 /**
4242  * Determine if a C++ constructor is a copy constructor.
4243  */
4245 
4246 /**
4247  * Determine if a C++ constructor is the default constructor.
4248  */
4250 
4251 /**
4252  * Determine if a C++ constructor is a move constructor.
4253  */
4255 
4256 /**
4257  * Determine if a C++ field is declared 'mutable'.
4258  */
4260 
4261 /**
4262  * Determine if a C++ method is declared '= default'.
4263  */
4265 
4266 /**
4267  * Determine if a C++ method is declared '= delete'.
4268  */
4270 
4271 /**
4272  * Determine if a C++ member function or member function template is
4273  * pure virtual.
4274  */
4276 
4277 /**
4278  * Determine if a C++ member function or member function template is
4279  * declared 'static'.
4280  */
4282 
4283 /**
4284  * Determine if a C++ member function or member function template is
4285  * explicitly declared 'virtual' or if it overrides a virtual method from
4286  * one of the base classes.
4287  */
4289 
4290 /**
4291  * Determine if a C++ member function is a copy-assignment operator,
4292  * returning 1 if such is the case and 0 otherwise.
4293  *
4294  * > A copy-assignment operator `X::operator=` is a non-static,
4295  * > non-template member function of _class_ `X` with exactly one
4296  * > parameter of type `X`, `X&`, `const X&`, `volatile X&` or `const
4297  * > volatile X&`.
4298  *
4299  * That is, for example, the `operator=` in:
4300  *
4301  * class Foo {
4302  * bool operator=(const volatile Foo&);
4303  * };
4304  *
4305  * Is a copy-assignment operator, while the `operator=` in:
4306  *
4307  * class Bar {
4308  * bool operator=(const int&);
4309  * };
4310  *
4311  * Is not.
4312  */
4314 
4315 /**
4316  * Determine if a C++ member function is a move-assignment operator,
4317  * returning 1 if such is the case and 0 otherwise.
4318  *
4319  * > A move-assignment operator `X::operator=` is a non-static,
4320  * > non-template member function of _class_ `X` with exactly one
4321  * > parameter of type `X&&`, `const X&&`, `volatile X&&` or `const
4322  * > volatile X&&`.
4323  *
4324  * That is, for example, the `operator=` in:
4325  *
4326  * class Foo {
4327  * bool operator=(const volatile Foo&&);
4328  * };
4329  *
4330  * Is a move-assignment operator, while the `operator=` in:
4331  *
4332  * class Bar {
4333  * bool operator=(const int&&);
4334  * };
4335  *
4336  * Is not.
4337  */
4339 
4340 /**
4341  * Determine if a C++ record is abstract, i.e. whether a class or struct
4342  * has a pure virtual member function.
4343  */
4345 
4346 /**
4347  * Determine if an enum declaration refers to a scoped enum.
4348  */
4350 
4351 /**
4352  * Determine if a C++ member function or member function template is
4353  * declared 'const'.
4354  */
4356 
4357 /**
4358  * Given a cursor that represents a template, determine
4359  * the cursor kind of the specializations would be generated by instantiating
4360  * the template.
4361  *
4362  * This routine can be used to determine what flavor of function template,
4363  * class template, or class template partial specialization is stored in the
4364  * cursor. For example, it can describe whether a class template cursor is
4365  * declared with "struct", "class" or "union".
4366  *
4367  * \param C The cursor to query. This cursor should represent a template
4368  * declaration.
4369  *
4370  * \returns The cursor kind of the specializations that would be generated
4371  * by instantiating the template \p C. If \p C is not a template, returns
4372  * \c CXCursor_NoDeclFound.
4373  */
4375 
4376 /**
4377  * Given a cursor that may represent a specialization or instantiation
4378  * of a template, retrieve the cursor that represents the template that it
4379  * specializes or from which it was instantiated.
4380  *
4381  * This routine determines the template involved both for explicit
4382  * specializations of templates and for implicit instantiations of the template,
4383  * both of which are referred to as "specializations". For a class template
4384  * specialization (e.g., \c std::vector<bool>), this routine will return
4385  * either the primary template (\c std::vector) or, if the specialization was
4386  * instantiated from a class template partial specialization, the class template
4387  * partial specialization. For a class template partial specialization and a
4388  * function template specialization (including instantiations), this
4389  * this routine will return the specialized template.
4390  *
4391  * For members of a class template (e.g., member functions, member classes, or
4392  * static data members), returns the specialized or instantiated member.
4393  * Although not strictly "templates" in the C++ language, members of class
4394  * templates have the same notions of specializations and instantiations that
4395  * templates do, so this routine treats them similarly.
4396  *
4397  * \param C A cursor that may be a specialization of a template or a member
4398  * of a template.
4399  *
4400  * \returns If the given cursor is a specialization or instantiation of a
4401  * template or a member thereof, the template or member that it specializes or
4402  * from which it was instantiated. Otherwise, returns a NULL cursor.
4403  */
4405 
4406 /**
4407  * Given a cursor that references something else, return the source range
4408  * covering that reference.
4409  *
4410  * \param C A cursor pointing to a member reference, a declaration reference, or
4411  * an operator call.
4412  * \param NameFlags A bitset with three independent flags:
4413  * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and
4414  * CXNameRange_WantSinglePiece.
4415  * \param PieceIndex For contiguous names or when passing the flag
4416  * CXNameRange_WantSinglePiece, only one piece with index 0 is
4417  * available. When the CXNameRange_WantSinglePiece flag is not passed for a
4418  * non-contiguous names, this index can be used to retrieve the individual
4419  * pieces of the name. See also CXNameRange_WantSinglePiece.
4420  *
4421  * \returns The piece of the name pointed to by the given cursor. If there is no
4422  * name, or if the PieceIndex is out-of-range, a null-cursor will be returned.
4423  */
4425  CXCursor C, unsigned NameFlags, unsigned PieceIndex);
4426 
4428  /**
4429  * Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the
4430  * range.
4431  */
4433 
4434  /**
4435  * Include the explicit template arguments, e.g. <int> in x.f<int>,
4436  * in the range.
4437  */
4439 
4440  /**
4441  * If the name is non-contiguous, return the full spanning range.
4442  *
4443  * Non-contiguous names occur in Objective-C when a selector with two or more
4444  * parameters is used, or in C++ when using an operator:
4445  * \code
4446  * [object doSomething:here withValue:there]; // Objective-C
4447  * return some_vector[1]; // C++
4448  * \endcode
4449  */
4451 };
4452 
4453 /**
4454  * @}
4455  */
4456 
4457 /**
4458  * \defgroup CINDEX_LEX Token extraction and manipulation
4459  *
4460  * The routines in this group provide access to the tokens within a
4461  * translation unit, along with a semantic mapping of those tokens to
4462  * their corresponding cursors.
4463  *
4464  * @{
4465  */
4466 
4467 /**
4468  * Describes a kind of token.
4469  */
4470 typedef enum CXTokenKind {
4471  /**
4472  * A token that contains some kind of punctuation.
4473  */
4475 
4476  /**
4477  * A language keyword.
4478  */
4480 
4481  /**
4482  * An identifier (that is not a keyword).
4483  */
4485 
4486  /**
4487  * A numeric, string, or character literal.
4488  */
4490 
4491  /**
4492  * A comment.
4493  */
4495 } CXTokenKind;
4496 
4497 /**
4498  * Describes a single preprocessing token.
4499  */
4500 typedef struct {
4501  unsigned int_data[4];
4502  void *ptr_data;
4503 } CXToken;
4504 
4505 /**
4506  * Get the raw lexical token starting with the given location.
4507  *
4508  * \param TU the translation unit whose text is being tokenized.
4509  *
4510  * \param Location the source location with which the token starts.
4511  *
4512  * \returns The token starting with the given location or NULL if no such token
4513  * exist. The returned pointer must be freed with clang_disposeTokens before the
4514  * translation unit is destroyed.
4515  */
4517  CXSourceLocation Location);
4518 
4519 /**
4520  * Determine the kind of the given token.
4521  */
4523 
4524 /**
4525  * Determine the spelling of the given token.
4526  *
4527  * The spelling of a token is the textual representation of that token, e.g.,
4528  * the text of an identifier or keyword.
4529  */
4531 
4532 /**
4533  * Retrieve the source location of the given token.
4534  */
4536  CXToken);
4537 
4538 /**
4539  * Retrieve a source range that covers the given token.
4540  */
4542 
4543 /**
4544  * Tokenize the source code described by the given range into raw
4545  * lexical tokens.
4546  *
4547  * \param TU the translation unit whose text is being tokenized.
4548  *
4549  * \param Range the source range in which text should be tokenized. All of the
4550  * tokens produced by tokenization will fall within this source range,
4551  *
4552  * \param Tokens this pointer will be set to point to the array of tokens
4553  * that occur within the given source range. The returned pointer must be
4554  * freed with clang_disposeTokens() before the translation unit is destroyed.
4555  *
4556  * \param NumTokens will be set to the number of tokens in the \c *Tokens
4557  * array.
4558  *
4559  */
4561  CXToken **Tokens, unsigned *NumTokens);
4562 
4563 /**
4564  * Annotate the given set of tokens by providing cursors for each token
4565  * that can be mapped to a specific entity within the abstract syntax tree.
4566  *
4567  * This token-annotation routine is equivalent to invoking
4568  * clang_getCursor() for the source locations of each of the
4569  * tokens. The cursors provided are filtered, so that only those
4570  * cursors that have a direct correspondence to the token are
4571  * accepted. For example, given a function call \c f(x),
4572  * clang_getCursor() would provide the following cursors:
4573  *
4574  * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'.
4575  * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'.
4576  * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'.
4577  *
4578  * Only the first and last of these cursors will occur within the
4579  * annotate, since the tokens "f" and "x' directly refer to a function
4580  * and a variable, respectively, but the parentheses are just a small
4581  * part of the full syntax of the function call expression, which is
4582  * not provided as an annotation.
4583  *
4584  * \param TU the translation unit that owns the given tokens.
4585  *
4586  * \param Tokens the set of tokens to annotate.
4587  *
4588  * \param NumTokens the number of tokens in \p Tokens.
4589  *
4590  * \param Cursors an array of \p NumTokens cursors, whose contents will be
4591  * replaced with the cursors corresponding to each token.
4592  */
4594  unsigned NumTokens, CXCursor *Cursors);
4595 
4596 /**
4597  * Free the given set of tokens.
4598  */
4600  unsigned NumTokens);
4601 
4602 /**
4603  * @}
4604  */
4605 
4606 /**
4607  * \defgroup CINDEX_DEBUG Debugging facilities
4608  *
4609  * These routines are used for testing and debugging, only, and should not
4610  * be relied upon.
4611  *
4612  * @{
4613  */
4614 
4615 /* for debug/testing */
4618  CXCursor, const char **startBuf, const char **endBuf, unsigned *startLine,
4619  unsigned *startColumn, unsigned *endLine, unsigned *endColumn);
4621 CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void *), void *user_data,
4622  unsigned stack_size);
4623 
4624 /**
4625  * @}
4626  */
4627 
4628 /**
4629  * \defgroup CINDEX_CODE_COMPLET Code completion
4630  *
4631  * Code completion involves taking an (incomplete) source file, along with
4632  * knowledge of where the user is actively editing that file, and suggesting
4633  * syntactically- and semantically-valid constructs that the user might want to
4634  * use at that particular point in the source code. These data structures and
4635  * routines provide support for code completion.
4636  *
4637  * @{
4638  */
4639 
4640 /**
4641  * A semantic string that describes a code-completion result.
4642  *
4643  * A semantic string that describes the formatting of a code-completion
4644  * result as a single "template" of text that should be inserted into the
4645  * source buffer when a particular code-completion result is selected.
4646  * Each semantic string is made up of some number of "chunks", each of which
4647  * contains some text along with a description of what that text means, e.g.,
4648  * the name of the entity being referenced, whether the text chunk is part of
4649  * the template, or whether it is a "placeholder" that the user should replace
4650  * with actual code,of a specific kind. See \c CXCompletionChunkKind for a
4651  * description of the different kinds of chunks.
4652  */
4653 typedef void *CXCompletionString;
4654 
4655 /**
4656  * A single result of code completion.
4657  */
4658 typedef struct {
4659  /**
4660  * The kind of entity that this completion refers to.
4661  *
4662  * The cursor kind will be a macro, keyword, or a declaration (one of the
4663  * *Decl cursor kinds), describing the entity that the completion is
4664  * referring to.
4665  *
4666  * \todo In the future, we would like to provide a full cursor, to allow
4667  * the client to extract additional information from declaration.
4668  */
4669  enum CXCursorKind CursorKind;
4670 
4671  /**
4672  * The code-completion string that describes how to insert this
4673  * code-completion result into the editing buffer.
4674  */
4677 
4678 /**
4679  * Describes a single piece of text within a code-completion string.
4680  *
4681  * Each "chunk" within a code-completion string (\c CXCompletionString) is
4682  * either a piece of text with a specific "kind" that describes how that text
4683  * should be interpreted by the client or is another completion string.
4684  */
4686  /**
4687  * A code-completion string that describes "optional" text that
4688  * could be a part of the template (but is not required).
4689  *
4690  * The Optional chunk is the only kind of chunk that has a code-completion
4691  * string for its representation, which is accessible via
4692  * \c clang_getCompletionChunkCompletionString(). The code-completion string
4693  * describes an additional part of the template that is completely optional.
4694  * For example, optional chunks can be used to describe the placeholders for
4695  * arguments that match up with defaulted function parameters, e.g. given:
4696  *
4697  * \code
4698  * void f(int x, float y = 3.14, double z = 2.71828);
4699  * \endcode
4700  *
4701  * The code-completion string for this function would contain:
4702  * - a TypedText chunk for "f".
4703  * - a LeftParen chunk for "(".
4704  * - a Placeholder chunk for "int x"
4705  * - an Optional chunk containing the remaining defaulted arguments, e.g.,
4706  * - a Comma chunk for ","
4707  * - a Placeholder chunk for "float y"
4708  * - an Optional chunk containing the last defaulted argument:
4709  * - a Comma chunk for ","
4710  * - a Placeholder chunk for "double z"
4711  * - a RightParen chunk for ")"
4712  *
4713  * There are many ways to handle Optional chunks. Two simple approaches are:
4714  * - Completely ignore optional chunks, in which case the template for the
4715  * function "f" would only include the first parameter ("int x").
4716  * - Fully expand all optional chunks, in which case the template for the
4717  * function "f" would have all of the parameters.
4718  */
4720  /**
4721  * Text that a user would be expected to type to get this
4722  * code-completion result.
4723  *
4724  * There will be exactly one "typed text" chunk in a semantic string, which
4725  * will typically provide the spelling of a keyword or the name of a
4726  * declaration that could be used at the current code point. Clients are
4727  * expected to filter the code-completion results based on the text in this
4728  * chunk.
4729  */
4731  /**
4732  * Text that should be inserted as part of a code-completion result.
4733  *
4734  * A "text" chunk represents text that is part of the template to be
4735  * inserted into user code should this particular code-completion result
4736  * be selected.
4737  */
4739  /**
4740  * Placeholder text that should be replaced by the user.
4741  *
4742  * A "placeholder" chunk marks a place where the user should insert text
4743  * into the code-completion template. For example, placeholders might mark
4744  * the function parameters for a function declaration, to indicate that the
4745  * user should provide arguments for each of those parameters. The actual
4746  * text in a placeholder is a suggestion for the text to display before
4747  * the user replaces the placeholder with real code.
4748  */
4750  /**
4751  * Informative text that should be displayed but never inserted as
4752  * part of the template.
4753  *
4754  * An "informative" chunk contains annotations that can be displayed to
4755  * help the user decide whether a particular code-completion result is the
4756  * right option, but which is not part of the actual template to be inserted
4757  * by code completion.
4758  */
4760  /**
4761  * Text that describes the current parameter when code-completion is
4762  * referring to function call, message send, or template specialization.
4763  *
4764  * A "current parameter" chunk occurs when code-completion is providing
4765  * information about a parameter corresponding to the argument at the
4766  * code-completion point. For example, given a function
4767  *
4768  * \code
4769  * int add(int x, int y);
4770  * \endcode
4771  *
4772  * and the source code \c add(, where the code-completion point is after the
4773  * "(", the code-completion string will contain a "current parameter" chunk
4774  * for "int x", indicating that the current argument will initialize that
4775  * parameter. After typing further, to \c add(17, (where the code-completion
4776  * point is after the ","), the code-completion string will contain a
4777  * "current parameter" chunk to "int y".
4778  */
4780  /**
4781  * A left parenthesis ('('), used to initiate a function call or
4782  * signal the beginning of a function parameter list.
4783  */
4785  /**
4786  * A right parenthesis (')'), used to finish a function call or
4787  * signal the end of a function parameter list.
4788  */
4790  /**
4791  * A left bracket ('[').
4792  */
4794  /**
4795  * A right bracket (']').
4796  */
4798  /**
4799  * A left brace ('{').
4800  */
4802  /**
4803  * A right brace ('}').
4804  */
4806  /**
4807  * A left angle bracket ('<').
4808  */
4810  /**
4811  * A right angle bracket ('>').
4812  */
4814  /**
4815  * A comma separator (',').
4816  */
4818  /**
4819  * Text that specifies the result type of a given result.
4820  *
4821  * This special kind of informative chunk is not meant to be inserted into
4822  * the text buffer. Rather, it is meant to illustrate the type that an
4823  * expression using the given completion string would have.
4824  */
4826  /**
4827  * A colon (':').
4828  */
4830  /**
4831  * A semicolon (';').
4832  */
4834  /**
4835  * An '=' sign.
4836  */
4838  /**
4839  * Horizontal space (' ').
4840  */
4842  /**
4843  * Vertical space ('\\n'), after which it is generally a good idea to
4844  * perform indentation.
4845  */
4847 };
4848 
4849 /**
4850  * Determine the kind of a particular chunk within a completion string.
4851  *
4852  * \param completion_string the completion string to query.
4853  *
4854  * \param chunk_number the 0-based index of the chunk in the completion string.
4855  *
4856  * \returns the kind of the chunk at the index \c chunk_number.
4857  */
4860  unsigned chunk_number);
4861 
4862 /**
4863  * Retrieve the text associated with a particular chunk within a
4864  * completion string.
4865  *
4866  * \param completion_string the completion string to query.
4867  *
4868  * \param chunk_number the 0-based index of the chunk in the completion string.
4869  *
4870  * \returns the text associated with the chunk at index \c chunk_number.
4871  */
4873  CXCompletionString completion_string, unsigned chunk_number);
4874 
4875 /**
4876  * Retrieve the completion string associated with a particular chunk
4877  * within a completion string.
4878  *
4879  * \param completion_string the completion string to query.
4880  *
4881  * \param chunk_number the 0-based index of the chunk in the completion string.
4882  *
4883  * \returns the completion string associated with the chunk at index
4884  * \c chunk_number.
4885  */
4887  CXCompletionString completion_string, unsigned chunk_number);
4888 
4889 /**
4890  * Retrieve the number of chunks in the given code-completion string.
4891  */
4892 CINDEX_LINKAGE unsigned
4894 
4895 /**
4896  * Determine the priority of this code completion.
4897  *
4898  * The priority of a code completion indicates how likely it is that this
4899  * particular completion is the completion that the user will select. The
4900  * priority is selected by various internal heuristics.
4901  *
4902  * \param completion_string The completion string to query.
4903  *
4904  * \returns The priority of this completion string. Smaller values indicate
4905  * higher-priority (more likely) completions.
4906  */
4907 CINDEX_LINKAGE unsigned
4909 
4910 /**
4911  * Determine the availability of the entity that this code-completion
4912  * string refers to.
4913  *
4914  * \param completion_string The completion string to query.
4915  *
4916  * \returns The availability of the completion string.
4917  */
4920 
4921 /**
4922  * Retrieve the number of annotations associated with the given
4923  * completion string.
4924  *
4925  * \param completion_string the completion string to query.
4926  *
4927  * \returns the number of annotations associated with the given completion
4928  * string.
4929  */
4930 CINDEX_LINKAGE unsigned
4932 
4933 /**
4934  * Retrieve the annotation associated with the given completion string.
4935  *
4936  * \param completion_string the completion string to query.
4937  *
4938  * \param annotation_number the 0-based index of the annotation of the
4939  * completion string.
4940  *
4941  * \returns annotation string associated with the completion at index
4942  * \c annotation_number, or a NULL string if that annotation is not available.
4943  */
4945  CXCompletionString completion_string, unsigned annotation_number);
4946 
4947 /**
4948  * Retrieve the parent context of the given completion string.
4949  *
4950  * The parent context of a completion string is the semantic parent of
4951  * the declaration (if any) that the code completion represents. For example,
4952  * a code completion for an Objective-C method would have the method's class
4953  * or protocol as its context.
4954  *
4955  * \param completion_string The code completion string whose parent is
4956  * being queried.
4957  *
4958  * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL.
4959  *
4960  * \returns The name of the completion parent, e.g., "NSObject" if
4961  * the completion string represents a method in the NSObject class.
4962  */
4964  CXCompletionString completion_string, enum CXCursorKind *kind);
4965 
4966 /**
4967  * Retrieve the brief documentation comment attached to the declaration
4968  * that corresponds to the given completion string.
4969  */
4972 
4973 /**
4974  * Retrieve a completion string for an arbitrary declaration or macro
4975  * definition cursor.
4976  *
4977  * \param cursor The cursor to query.
4978  *
4979  * \returns A non-context-sensitive completion string for declaration and macro
4980  * definition cursors, or NULL for other kinds of cursors.
4981  */
4984 
4985 /**
4986  * Contains the results of code-completion.
4987  *
4988  * This data structure contains the results of code completion, as
4989  * produced by \c clang_codeCompleteAt(). Its contents must be freed by
4990  * \c clang_disposeCodeCompleteResults.
4991  */
4992 typedef struct {
4993  /**
4994  * The code-completion results.
4995  */
4997 
4998  /**
4999  * The number of code-completion results stored in the
5000  * \c Results array.
5001  */
5002  unsigned NumResults;
5004 
5005 /**
5006  * Retrieve the number of fix-its for the given completion index.
5007  *
5008  * Calling this makes sense only if CXCodeComplete_IncludeCompletionsWithFixIts
5009  * option was set.
5010  *
5011  * \param results The structure keeping all completion results
5012  *
5013  * \param completion_index The index of the completion
5014  *
5015  * \return The number of fix-its which must be applied before the completion at
5016  * completion_index can be applied
5017  */
5018 CINDEX_LINKAGE unsigned
5020  unsigned completion_index);
5021 
5022 /**
5023  * Fix-its that *must* be applied before inserting the text for the
5024  * corresponding completion.
5025  *
5026  * By default, clang_codeCompleteAt() only returns completions with empty
5027  * fix-its. Extra completions with non-empty fix-its should be explicitly
5028  * requested by setting CXCodeComplete_IncludeCompletionsWithFixIts.
5029  *
5030  * For the clients to be able to compute position of the cursor after applying
5031  * fix-its, the following conditions are guaranteed to hold for
5032  * replacement_range of the stored fix-its:
5033  * - Ranges in the fix-its are guaranteed to never contain the completion
5034  * point (or identifier under completion point, if any) inside them, except
5035  * at the start or at the end of the range.
5036  * - If a fix-it range starts or ends with completion point (or starts or
5037  * ends after the identifier under completion point), it will contain at
5038  * least one character. It allows to unambiguously recompute completion
5039  * point after applying the fix-it.
5040  *
5041  * The intuition is that provided fix-its change code around the identifier we
5042  * complete, but are not allowed to touch the identifier itself or the
5043  * completion point. One example of completions with corrections are the ones
5044  * replacing '.' with '->' and vice versa:
5045  *
5046  * std::unique_ptr<std::vector<int>> vec_ptr;
5047  * In 'vec_ptr.^', one of the completions is 'push_back', it requires
5048  * replacing '.' with '->'.
5049  * In 'vec_ptr->^', one of the completions is 'release', it requires
5050  * replacing '->' with '.'.
5051  *
5052  * \param results The structure keeping all completion results
5053  *
5054  * \param completion_index The index of the completion
5055  *
5056  * \param fixit_index The index of the fix-it for the completion at
5057  * completion_index
5058  *
5059  * \param replacement_range The fix-it range that must be replaced before the
5060  * completion at completion_index can be applied
5061  *
5062  * \returns The fix-it string that must replace the code at replacement_range
5063  * before the completion at completion_index can be applied
5064  */
5066  CXCodeCompleteResults *results, unsigned completion_index,
5067  unsigned fixit_index, CXSourceRange *replacement_range);
5068 
5069 /**
5070  * Flags that can be passed to \c clang_codeCompleteAt() to
5071  * modify its behavior.
5072  *
5073  * The enumerators in this enumeration can be bitwise-OR'd together to
5074  * provide multiple options to \c clang_codeCompleteAt().
5075  */
5077  /**
5078  * Whether to include macros within the set of code
5079  * completions returned.
5080  */
5082 
5083  /**
5084  * Whether to include code patterns for language constructs
5085  * within the set of code completions, e.g., for loops.
5086  */
5088 
5089  /**
5090  * Whether to include brief documentation within the set of code
5091  * completions returned.
5092  */
5094 
5095  /**
5096  * Whether to speed up completion by omitting top- or namespace-level entities
5097  * defined in the preamble. There's no guarantee any particular entity is
5098  * omitted. This may be useful if the headers are indexed externally.
5099  */
5101 
5102  /**
5103  * Whether to include completions with small
5104  * fix-its, e.g. change '.' to '->' on member access, etc.
5105  */
5107 };
5108 
5109 /**
5110  * Bits that represent the context under which completion is occurring.
5111  *
5112  * The enumerators in this enumeration may be bitwise-OR'd together if multiple
5113  * contexts are occurring simultaneously.
5114  */
5116  /**
5117  * The context for completions is unexposed, as only Clang results
5118  * should be included. (This is equivalent to having no context bits set.)
5119  */
5121 
5122  /**
5123  * Completions for any possible type should be included in the results.
5124  */
5126 
5127  /**
5128  * Completions for any possible value (variables, function calls, etc.)
5129  * should be included in the results.
5130  */
5132  /**
5133  * Completions for values that resolve to an Objective-C object should
5134  * be included in the results.
5135  */
5137  /**
5138  * Completions for values that resolve to an Objective-C selector
5139  * should be included in the results.
5140  */
5142  /**
5143  * Completions for values that resolve to a C++ class type should be
5144  * included in the results.
5145  */
5147 
5148  /**
5149  * Completions for fields of the member being accessed using the dot
5150  * operator should be included in the results.
5151  */
5153  /**
5154  * Completions for fields of the member being accessed using the arrow
5155  * operator should be included in the results.
5156  */
5158  /**
5159  * Completions for properties of the Objective-C object being accessed
5160  * using the dot operator should be included in the results.
5161  */
5163 
5164  /**
5165  * Completions for enum tags should be included in the results.
5166  */
5168  /**
5169  * Completions for union tags should be included in the results.
5170  */
5172  /**
5173  * Completions for struct tags should be included in the results.
5174  */
5176 
5177  /**
5178  * Completions for C++ class names should be included in the results.
5179  */
5181  /**
5182  * Completions for C++ namespaces and namespace aliases should be
5183  * included in the results.
5184  */
5186  /**
5187  * Completions for C++ nested name specifiers should be included in
5188  * the results.
5189  */
5191 
5192  /**
5193  * Completions for Objective-C interfaces (classes) should be included
5194  * in the results.
5195  */
5197  /**
5198  * Completions for Objective-C protocols should be included in
5199  * the results.
5200  */
5202  /**
5203  * Completions for Objective-C categories should be included in
5204  * the results.
5205  */
5207  /**
5208  * Completions for Objective-C instance messages should be included
5209  * in the results.
5210  */
5212  /**
5213  * Completions for Objective-C class messages should be included in
5214  * the results.
5215  */
5217  /**
5218  * Completions for Objective-C selector names should be included in
5219  * the results.
5220  */
5222 
5223  /**
5224  * Completions for preprocessor macro names should be included in
5225  * the results.
5226  */
5228 
5229  /**
5230  * Natural language completions should be included in the results.
5231  */
5233 
5234  /**
5235  * #include file completions should be included in the results.
5236  */
5238 
5239  /**
5240  * The current context is unknown, so set all contexts.
5241  */
5243 };
5244 
5245 /**
5246  * Returns a default set of code-completion options that can be
5247  * passed to\c clang_codeCompleteAt().
5248  */
5250 
5251 /**
5252  * Perform code completion at a given location in a translation unit.
5253  *
5254  * This function performs code completion at a particular file, line, and
5255  * column within source code, providing results that suggest potential
5256  * code snippets based on the context of the completion. The basic model
5257  * for code completion is that Clang will parse a complete source file,
5258  * performing syntax checking up to the location where code-completion has
5259  * been requested. At that point, a special code-completion token is passed
5260  * to the parser, which recognizes this token and determines, based on the
5261  * current location in the C/Objective-C/C++ grammar and the state of
5262  * semantic analysis, what completions to provide. These completions are
5263  * returned via a new \c CXCodeCompleteResults structure.
5264  *
5265  * Code completion itself is meant to be triggered by the client when the
5266  * user types punctuation characters or whitespace, at which point the
5267  * code-completion location will coincide with the cursor. For example, if \c p
5268  * is a pointer, code-completion might be triggered after the "-" and then
5269  * after the ">" in \c p->. When the code-completion location is after the ">",
5270  * the completion results will provide, e.g., the members of the struct that
5271  * "p" points to. The client is responsible for placing the cursor at the
5272  * beginning of the token currently being typed, then filtering the results
5273  * based on the contents of the token. For example, when code-completing for
5274  * the expression \c p->get, the client should provide the location just after
5275  * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the
5276  * client can filter the results based on the current token text ("get"), only
5277  * showing those results that start with "get". The intent of this interface
5278  * is to separate the relatively high-latency acquisition of code-completion
5279  * results from the filtering of results on a per-character basis, which must
5280  * have a lower latency.
5281  *
5282  * \param TU The translation unit in which code-completion should
5283  * occur. The source files for this translation unit need not be
5284  * completely up-to-date (and the contents of those source files may
5285  * be overridden via \p unsaved_files). Cursors referring into the
5286  * translation unit may be invalidated by this invocation.
5287  *
5288  * \param complete_filename The name of the source file where code
5289  * completion should be performed. This filename may be any file
5290  * included in the translation unit.
5291  *
5292  * \param complete_line The line at which code-completion should occur.
5293  *
5294  * \param complete_column The column at which code-completion should occur.
5295  * Note that the column should point just after the syntactic construct that
5296  * initiated code completion, and not in the middle of a lexical token.
5297  *
5298  * \param unsaved_files the Files that have not yet been saved to disk
5299  * but may be required for parsing or code completion, including the
5300  * contents of those files. The contents and name of these files (as
5301  * specified by CXUnsavedFile) are copied when necessary, so the
5302  * client only needs to guarantee their validity until the call to
5303  * this function returns.
5304  *
5305  * \param num_unsaved_files The number of unsaved file entries in \p
5306  * unsaved_files.
5307  *
5308  * \param options Extra options that control the behavior of code
5309  * completion, expressed as a bitwise OR of the enumerators of the
5310  * CXCodeComplete_Flags enumeration. The
5311  * \c clang_defaultCodeCompleteOptions() function returns a default set
5312  * of code-completion options.
5313  *
5314  * \returns If successful, a new \c CXCodeCompleteResults structure
5315  * containing code-completion results, which should eventually be
5316  * freed with \c clang_disposeCodeCompleteResults(). If code
5317  * completion fails, returns NULL.
5318  */
5321 clang_codeCompleteAt(CXTranslationUnit TU, const char *complete_filename,
5322  unsigned complete_line, unsigned complete_column,
5323  struct CXUnsavedFile *unsaved_files,
5324  unsigned num_unsaved_files, unsigned options);
5325 
5326 /**
5327  * Sort the code-completion results in case-insensitive alphabetical
5328  * order.
5329  *
5330  * \param Results The set of results to sort.
5331  * \param NumResults The number of results in \p Results.
5332  */
5335  unsigned NumResults);
5336 
5337 /**
5338  * Free the given set of code-completion results.
5339  */
5342 
5343 /**
5344  * Determine the number of diagnostics produced prior to the
5345  * location where code completion was performed.
5346  */
5349 
5350 /**
5351  * Retrieve a diagnostic associated with the given code completion.
5352  *
5353  * \param Results the code completion results to query.
5354  * \param Index the zero-based diagnostic number to retrieve.
5355  *
5356  * \returns the requested diagnostic. This diagnostic must be freed
5357  * via a call to \c clang_disposeDiagnostic().
5358  */
5361  unsigned Index);
5362 
5363 /**
5364  * Determines what completions are appropriate for the context
5365  * the given code completion.
5366  *
5367  * \param Results the code completion results to query
5368  *
5369  * \returns the kinds of completions that are appropriate for use
5370  * along with the given code completion results.
5371  */
5373 unsigned long long
5375 
5376 /**
5377  * Returns the cursor kind for the container for the current code
5378  * completion context. The container is only guaranteed to be set for
5379  * contexts where a container exists (i.e. member accesses or Objective-C
5380  * message sends); if there is not a container, this function will return
5381  * CXCursor_InvalidCode.
5382  *
5383  * \param Results the code completion results to query
5384  *
5385  * \param IsIncomplete on return, this value will be false if Clang has complete
5386  * information about the container. If Clang does not have complete
5387  * information, this value will be true.
5388  *
5389  * \returns the container kind, or CXCursor_InvalidCode if there is not a
5390  * container
5391  */
5393 enum CXCursorKind
5395  unsigned *IsIncomplete);
5396 
5397 /**
5398  * Returns the USR for the container for the current code completion
5399  * context. If there is not a container for the current context, this
5400  * function will return the empty string.
5401  *
5402  * \param Results the code completion results to query
5403  *
5404  * \returns the USR for the container
5405  */
5408 
5409 /**
5410  * Returns the currently-entered selector for an Objective-C message
5411  * send, formatted like "initWithFoo:bar:". Only guaranteed to return a
5412  * non-empty string for CXCompletionContext_ObjCInstanceMessage and
5413  * CXCompletionContext_ObjCClassMessage.
5414  *
5415  * \param Results the code completion results to query
5416  *
5417  * \returns the selector (or partial selector) that has been entered thus far
5418  * for an Objective-C message send.
5419  */
5422 
5423 /**
5424  * @}
5425  */
5426 
5427 /**
5428  * \defgroup CINDEX_MISC Miscellaneous utility functions
5429  *
5430  * @{
5431  */
5432 
5433 /**
5434  * Return a version string, suitable for showing to a user, but not
5435  * intended to be parsed (the format is not guaranteed to be stable).
5436  */
5438 
5439 /**
5440  * Enable/disable crash recovery.
5441  *
5442  * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero
5443  * value enables crash recovery, while 0 disables it.
5444  */
5446 
5447 /**
5448  * Visitor invoked for each file in a translation unit
5449  * (used with clang_getInclusions()).
5450  *
5451  * This visitor function will be invoked by clang_getInclusions() for each
5452  * file included (either at the top-level or by \#include directives) within
5453  * a translation unit. The first argument is the file being included, and
5454  * the second and third arguments provide the inclusion stack. The
5455  * array is sorted in order of immediate inclusion. For example,
5456  * the first element refers to the location that included 'included_file'.
5457  */
5458 typedef void (*CXInclusionVisitor)(CXFile included_file,
5459  CXSourceLocation *inclusion_stack,
5460  unsigned include_len,
5461  CXClientData client_data);
5462 
5463 /**
5464  * Visit the set of preprocessor inclusions in a translation unit.
5465  * The visitor function is called with the provided data for every included
5466  * file. This does not include headers included by the PCH file (unless one
5467  * is inspecting the inclusions in the PCH file itself).
5468  */
5470  CXInclusionVisitor visitor,
5471  CXClientData client_data);
5472 
5473 typedef enum {
5480 
5482 
5484 
5485 /**
5486  * Evaluation result of a cursor
5487  */
5488 typedef void *CXEvalResult;
5489 
5490 /**
5491  * If cursor is a statement declaration tries to evaluate the
5492  * statement and if its variable, tries to evaluate its initializer,
5493  * into its corresponding type.
5494  * If it's an expression, tries to evaluate the expression.
5495  */
5497 
5498 /**
5499  * Returns the kind of the evaluated result.
5500  */
5502 
5503 /**
5504  * Returns the evaluation result as integer if the
5505  * kind is Int.
5506  */
5508 
5509 /**
5510  * Returns the evaluation result as a long long integer if the
5511  * kind is Int. This prevents overflows that may happen if the result is
5512  * returned with clang_EvalResult_getAsInt.
5513  */
5515 
5516 /**
5517  * Returns a non-zero value if the kind is Int and the evaluation
5518  * result resulted in an unsigned integer.
5519  */
5521 
5522 /**
5523  * Returns the evaluation result as an unsigned integer if
5524  * the kind is Int and clang_EvalResult_isUnsignedInt is non-zero.
5525  */
5526 CINDEX_LINKAGE unsigned long long
5528 
5529 /**
5530  * Returns the evaluation result as double if the
5531  * kind is double.
5532  */
5534 
5535 /**
5536  * Returns the evaluation result as a constant string if the
5537  * kind is other than Int or float. User must not free this pointer,
5538  * instead call clang_EvalResult_dispose on the CXEvalResult returned
5539  * by clang_Cursor_Evaluate.
5540  */
5542