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