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