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