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