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