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