Debian Codegraph @

llvm-project/clang/include/clang-c/Index.h

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