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