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