Index.h revision 04bb716aea8fd2372ac10b0c640cabc5e5caa615
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 22#ifdef __cplusplus 23extern "C" { 24#endif 25 26/* MSVC DLL import/export. */ 27#ifdef _MSC_VER 28 #ifdef _CINDEX_LIB_ 29 #define CINDEX_LINKAGE __declspec(dllexport) 30 #else 31 #define CINDEX_LINKAGE __declspec(dllimport) 32 #endif 33#else 34 #define CINDEX_LINKAGE 35#endif 36 37/** \defgroup CINDEX C Interface to Clang 38 * 39 * The C Interface to Clang provides a relatively small API that exposes 40 * facilities for parsing source code into an abstract syntax tree (AST), 41 * loading already-parsed ASTs, traversing the AST, associating 42 * physical source locations with elements within the AST, and other 43 * facilities that support Clang-based development tools. 44 * 45 * This C interface to Clang will never provide all of the information 46 * representation stored in Clang's C++ AST, nor should it: the intent is to 47 * maintain an API that is relatively stable from one release to the next, 48 * providing only the basic functionality needed to support development tools. 49 * 50 * To avoid namespace pollution, data types are prefixed with "CX" and 51 * functions are prefixed with "clang_". 52 * 53 * @{ 54 */ 55 56/** 57 * \brief An "index" that consists of a set of translation units that would 58 * typically be linked together into an executable or library. 59 */ 60typedef void *CXIndex; 61 62/** 63 * \brief A single translation unit, which resides in an index. 64 */ 65typedef void *CXTranslationUnit; /* A translation unit instance. */ 66 67/** 68 * \brief Opaque pointer representing client data that will be passed through 69 * to various callbacks and visitors. 70 */ 71typedef void *CXClientData; 72 73/** 74 * \brief Provides the contents of a file that has not yet been saved to disk. 75 * 76 * Each CXUnsavedFile instance provides the name of a file on the 77 * system along with the current contents of that file that have not 78 * yet been saved to disk. 79 */ 80struct CXUnsavedFile { 81 /** 82 * \brief The file whose contents have not yet been saved. 83 * 84 * This file must already exist in the file system. 85 */ 86 const char *Filename; 87 88 /** 89 * \brief A null-terminated buffer containing the unsaved contents 90 * of this file. 91 */ 92 const char *Contents; 93 94 /** 95 * \brief The length of the unsaved contents of this buffer, not 96 * counting the NULL at the end of the buffer. 97 */ 98 unsigned long Length; 99}; 100 101/** 102 * \defgroup CINDEX_STRING String manipulation routines 103 * 104 * @{ 105 */ 106 107/** 108 * \brief A character string. 109 * 110 * The \c CXString type is used to return strings from the interface when 111 * the ownership of that string might different from one call to the next. 112 * Use \c clang_getCString() to retrieve the string data and, once finished 113 * with the string data, call \c clang_disposeString() to free the string. 114 */ 115typedef struct { 116 const char *Spelling; 117 /* A 1 value indicates the clang_ indexing API needed to allocate the string 118 (and it must be freed by clang_disposeString()). */ 119 int MustFreeString; 120} CXString; 121 122/** 123 * \brief Retrieve the character data associated with the given string. 124 */ 125CINDEX_LINKAGE const char *clang_getCString(CXString string); 126 127/** 128 * \brief Free the given string, 129 */ 130CINDEX_LINKAGE void clang_disposeString(CXString string); 131 132/** 133 * @} 134 */ 135 136/** 137 * \brief clang_createIndex() provides a shared context for creating 138 * translation units. It provides two options: 139 * 140 * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 141 * declarations (when loading any new translation units). A "local" declaration 142 * is one that belongs in the translation unit itself and not in a precompiled 143 * header that was used by the translation unit. If zero, all declarations 144 * will be enumerated. 145 * 146 * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, 147 * diagnostics will be ignored. 148 * 149 * Here is an example: 150 * 151 * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 152 * Idx = clang_createIndex(1, 1); 153 * 154 * // IndexTest.pch was produced with the following command: 155 * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 156 * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 157 * 158 * // This will load all the symbols from 'IndexTest.pch' 159 * clang_visitChildren(clang_getTranslationUnitCursor(TU), 160 * TranslationUnitVisitor, 0); 161 * clang_disposeTranslationUnit(TU); 162 * 163 * // This will load all the symbols from 'IndexTest.c', excluding symbols 164 * // from 'IndexTest.pch'. 165 * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; 166 * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); 167 * clang_visitChildren(clang_getTranslationUnitCursor(TU), 168 * TranslationUnitVisitor, 0); 169 * clang_disposeTranslationUnit(TU); 170 * 171 * This process of creating the 'pch', loading it separately, and using it (via 172 * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 173 * (which gives the indexer the same performance benefit as the compiler). 174 */ 175CINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 176 int displayDiagnostics); 177CINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 178CINDEX_LINKAGE CXString 179clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 180 181/** 182 * \brief Request that AST's be generated external for API calls which parse 183 * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. 184 * 185 * Note: This is for debugging purposes only, and may be removed at a later 186 * date. 187 * 188 * \param index - The index to update. 189 * \param value - The new flag value. 190 */ 191CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, 192 int value); 193 194/** 195 * \brief Create a translation unit from an AST file (-emit-ast). 196 */ 197CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( 198 CXIndex, const char *ast_filename 199); 200 201/** 202 * \brief Destroy the specified CXTranslationUnit object. 203 */ 204CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 205 206/** 207 * \brief Return the CXTranslationUnit for a given source file and the provided 208 * command line arguments one would pass to the compiler. 209 * 210 * Note: The 'source_filename' argument is optional. If the caller provides a 211 * NULL pointer, the name of the source file is expected to reside in the 212 * specified command line arguments. 213 * 214 * Note: When encountered in 'clang_command_line_args', the following options 215 * are ignored: 216 * 217 * '-c' 218 * '-emit-ast' 219 * '-fsyntax-only' 220 * '-o <output file>' (both '-o' and '<output file>' are ignored) 221 * 222 * 223 * \param source_filename - The name of the source file to load, or NULL if the 224 * source file is included in clang_command_line_args. 225 */ 226CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 227 CXIndex CIdx, 228 const char *source_filename, 229 int num_clang_command_line_args, 230 const char **clang_command_line_args 231); 232 233/** 234 * \defgroup CINDEX_FILES File manipulation routines 235 * 236 * @{ 237 */ 238 239/** 240 * \brief A particular source file that is part of a translation unit. 241 */ 242typedef void *CXFile; 243 244 245/** 246 * \brief Retrieve the complete file and path name of the given file. 247 */ 248CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); 249 250/** 251 * \brief Retrieve the last modification time of the given file. 252 */ 253CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 254 255/** 256 * \brief Retrieve a file handle within the given translation unit. 257 * 258 * \param tu the translation unit 259 * 260 * \param file_name the name of the file. 261 * 262 * \returns the file handle for the named file in the translation unit \p tu, 263 * or a NULL file handle if the file was not a part of this translation unit. 264 */ 265CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, 266 const char *file_name); 267 268/** 269 * @} 270 */ 271 272/** 273 * \defgroup CINDEX_LOCATIONS Physical source locations 274 * 275 * Clang represents physical source locations in its abstract syntax tree in 276 * great detail, with file, line, and column information for the majority of 277 * the tokens parsed in the source code. These data types and functions are 278 * used to represent source location information, either for a particular 279 * point in the program or for a range of points in the program, and extract 280 * specific location information from those data types. 281 * 282 * @{ 283 */ 284 285/** 286 * \brief Identifies a specific source location within a translation 287 * unit. 288 * 289 * Use clang_getInstantiationLocation() to map a source location to a 290 * particular file, line, and column. 291 */ 292typedef struct { 293 void *ptr_data; 294 unsigned int_data; 295} CXSourceLocation; 296 297/** 298 * \brief Identifies a range of source locations in the source code. 299 * 300 * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 301 * starting and end locations from a source range, respectively. 302 */ 303typedef struct { 304 void *ptr_data; 305 unsigned begin_int_data; 306 unsigned end_int_data; 307} CXSourceRange; 308 309/** 310 * \brief Retrieve a NULL (invalid) source location. 311 */ 312CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); 313 314/** 315 * \determine Determine whether two source locations, which must refer into 316 * the same translation unit, refer to exactly the same point in the source 317 * code. 318 * 319 * \returns non-zero if the source locations refer to the same location, zero 320 * if they refer to different locations. 321 */ 322CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 323 CXSourceLocation loc2); 324 325/** 326 * \brief Retrieves the source location associated with a given 327 * file/line/column in a particular translation unit. 328 */ 329CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, 330 CXFile file, 331 unsigned line, 332 unsigned column); 333 334/** 335 * \brief Retrieve a source range given the beginning and ending source 336 * locations. 337 */ 338CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 339 CXSourceLocation end); 340 341/** 342 * \brief Retrieve the file, line, and column represented by the 343 * given source location. 344 * 345 * \param location the location within a source file that will be 346 * decomposed into its parts. 347 * 348 * \param file if non-NULL, will be set to the file to which the given 349 * source location points. 350 * 351 * \param line if non-NULL, will be set to the line to which the given 352 * source location points. 353 * 354 * \param column if non-NULL, will be set to the column to which the 355 * given source location points. 356 */ 357CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 358 CXFile *file, 359 unsigned *line, 360 unsigned *column); 361 362/** 363 * \brief Retrieve a source location representing the first 364 * character within a source range. 365 */ 366CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 367 368/** 369 * \brief Retrieve a source location representing the last 370 * character within a source range. 371 */ 372CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 373 374/** 375 * @} 376 */ 377 378/** 379 * \brief Describes the kind of entity that a cursor refers to. 380 */ 381enum CXCursorKind { 382 /* Declarations */ 383 CXCursor_FirstDecl = 1, 384 /** 385 * \brief A declaration whose specific kind is not exposed via this 386 * interface. 387 * 388 * Unexposed declarations have the same operations as any other kind 389 * of declaration; one can extract their location information, 390 * spelling, find their definitions, etc. However, the specific kind 391 * of the declaration is not reported. 392 */ 393 CXCursor_UnexposedDecl = 1, 394 /** \brief A C or C++ struct. */ 395 CXCursor_StructDecl = 2, 396 /** \brief A C or C++ union. */ 397 CXCursor_UnionDecl = 3, 398 /** \brief A C++ class. */ 399 CXCursor_ClassDecl = 4, 400 /** \brief An enumeration. */ 401 CXCursor_EnumDecl = 5, 402 /** 403 * \brief A field (in C) or non-static data member (in C++) in a 404 * struct, union, or C++ class. 405 */ 406 CXCursor_FieldDecl = 6, 407 /** \brief An enumerator constant. */ 408 CXCursor_EnumConstantDecl = 7, 409 /** \brief A function. */ 410 CXCursor_FunctionDecl = 8, 411 /** \brief A variable. */ 412 CXCursor_VarDecl = 9, 413 /** \brief A function or method parameter. */ 414 CXCursor_ParmDecl = 10, 415 /** \brief An Objective-C @interface. */ 416 CXCursor_ObjCInterfaceDecl = 11, 417 /** \brief An Objective-C @interface for a category. */ 418 CXCursor_ObjCCategoryDecl = 12, 419 /** \brief An Objective-C @protocol declaration. */ 420 CXCursor_ObjCProtocolDecl = 13, 421 /** \brief An Objective-C @property declaration. */ 422 CXCursor_ObjCPropertyDecl = 14, 423 /** \brief An Objective-C instance variable. */ 424 CXCursor_ObjCIvarDecl = 15, 425 /** \brief An Objective-C instance method. */ 426 CXCursor_ObjCInstanceMethodDecl = 16, 427 /** \brief An Objective-C class method. */ 428 CXCursor_ObjCClassMethodDecl = 17, 429 /** \brief An Objective-C @implementation. */ 430 CXCursor_ObjCImplementationDecl = 18, 431 /** \brief An Objective-C @implementation for a category. */ 432 CXCursor_ObjCCategoryImplDecl = 19, 433 /** \brief A typedef */ 434 CXCursor_TypedefDecl = 20, 435 CXCursor_LastDecl = 20, 436 437 /* References */ 438 CXCursor_FirstRef = 40, /* Decl references */ 439 CXCursor_ObjCSuperClassRef = 40, 440 CXCursor_ObjCProtocolRef = 41, 441 CXCursor_ObjCClassRef = 42, 442 /** 443 * \brief A reference to a type declaration. 444 * 445 * A type reference occurs anywhere where a type is named but not 446 * declared. For example, given: 447 * 448 * \code 449 * typedef unsigned size_type; 450 * size_type size; 451 * \endcode 452 * 453 * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 454 * while the type of the variable "size" is referenced. The cursor 455 * referenced by the type of size is the typedef for size_type. 456 */ 457 CXCursor_TypeRef = 43, 458 CXCursor_LastRef = 43, 459 460 /* Error conditions */ 461 CXCursor_FirstInvalid = 70, 462 CXCursor_InvalidFile = 70, 463 CXCursor_NoDeclFound = 71, 464 CXCursor_NotImplemented = 72, 465 CXCursor_LastInvalid = 72, 466 467 /* Expressions */ 468 CXCursor_FirstExpr = 100, 469 470 /** 471 * \brief An expression whose specific kind is not exposed via this 472 * interface. 473 * 474 * Unexposed expressions have the same operations as any other kind 475 * of expression; one can extract their location information, 476 * spelling, children, etc. However, the specific kind of the 477 * expression is not reported. 478 */ 479 CXCursor_UnexposedExpr = 100, 480 481 /** 482 * \brief An expression that refers to some value declaration, such 483 * as a function, varible, or enumerator. 484 */ 485 CXCursor_DeclRefExpr = 101, 486 487 /** 488 * \brief An expression that refers to a member of a struct, union, 489 * class, Objective-C class, etc. 490 */ 491 CXCursor_MemberRefExpr = 102, 492 493 /** \brief An expression that calls a function. */ 494 CXCursor_CallExpr = 103, 495 496 /** \brief An expression that sends a message to an Objective-C 497 object or class. */ 498 CXCursor_ObjCMessageExpr = 104, 499 CXCursor_LastExpr = 104, 500 501 /* Statements */ 502 CXCursor_FirstStmt = 200, 503 /** 504 * \brief A statement whose specific kind is not exposed via this 505 * interface. 506 * 507 * Unexposed statements have the same operations as any other kind of 508 * statement; one can extract their location information, spelling, 509 * children, etc. However, the specific kind of the statement is not 510 * reported. 511 */ 512 CXCursor_UnexposedStmt = 200, 513 CXCursor_LastStmt = 200, 514 515 /** 516 * \brief Cursor that represents the translation unit itself. 517 * 518 * The translation unit cursor exists primarily to act as the root 519 * cursor for traversing the contents of a translation unit. 520 */ 521 CXCursor_TranslationUnit = 300 522}; 523 524/** 525 * \brief A cursor representing some element in the abstract syntax tree for 526 * a translation unit. 527 * 528 * The cursor abstraction unifies the different kinds of entities in a 529 * program--declaration, statements, expressions, references to declarations, 530 * etc.--under a single "cursor" abstraction with a common set of operations. 531 * Common operation for a cursor include: getting the physical location in 532 * a source file where the cursor points, getting the name associated with a 533 * cursor, and retrieving cursors for any child nodes of a particular cursor. 534 * 535 * Cursors can be produced in two specific ways. 536 * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 537 * from which one can use clang_visitChildren() to explore the rest of the 538 * translation unit. clang_getCursor() maps from a physical source location 539 * to the entity that resides at that location, allowing one to map from the 540 * source code into the AST. 541 */ 542typedef struct { 543 enum CXCursorKind kind; 544 void *data[3]; 545} CXCursor; 546 547/** 548 * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 549 * 550 * @{ 551 */ 552 553/** 554 * \brief Retrieve the NULL cursor, which represents no entity. 555 */ 556CINDEX_LINKAGE CXCursor clang_getNullCursor(void); 557 558/** 559 * \brief Retrieve the cursor that represents the given translation unit. 560 * 561 * The translation unit cursor can be used to start traversing the 562 * various declarations within the given translation unit. 563 */ 564CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 565 566/** 567 * \brief Determine whether two cursors are equivalent. 568 */ 569CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 570 571/** 572 * \brief Retrieve the kind of the given cursor. 573 */ 574CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 575 576/** 577 * \brief Determine whether the given cursor kind represents a declaration. 578 */ 579CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 580 581/** 582 * \brief Determine whether the given cursor kind represents a simple 583 * reference. 584 * 585 * Note that other kinds of cursors (such as expressions) can also refer to 586 * other cursors. Use clang_getCursorReferenced() to determine whether a 587 * particular cursor refers to another entity. 588 */ 589CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 590 591/** 592 * \brief Determine whether the given cursor kind represents an expression. 593 */ 594CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 595 596/** 597 * \brief Determine whether the given cursor kind represents a statement. 598 */ 599CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 600 601/** 602 * \brief Determine whether the given cursor kind represents an invalid 603 * cursor. 604 */ 605CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 606 607/** 608 * \brief Determine whether the given cursor kind represents a translation 609 * unit. 610 */ 611CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 612 613/** 614 * @} 615 */ 616 617/** 618 * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 619 * 620 * Cursors represent a location within the Abstract Syntax Tree (AST). These 621 * routines help map between cursors and the physical locations where the 622 * described entities occur in the source code. The mapping is provided in 623 * both directions, so one can map from source code to the AST and back. 624 * 625 * @{ 626 */ 627 628/** 629 * \brief Map a source location to the cursor that describes the entity at that 630 * location in the source code. 631 * 632 * clang_getCursor() maps an arbitrary source location within a translation 633 * unit down to the most specific cursor that describes the entity at that 634 * location. For example, given an expression \c x + y, invoking 635 * clang_getCursor() with a source location pointing to "x" will return the 636 * cursor for "x"; similarly for "y". If the cursor points anywhere between 637 * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 638 * will return a cursor referring to the "+" expression. 639 * 640 * \returns a cursor representing the entity at the given source location, or 641 * a NULL cursor if no such entity can be found. 642 */ 643CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 644 645/** 646 * \brief Retrieve the physical location of the source constructor referenced 647 * by the given cursor. 648 * 649 * The location of a declaration is typically the location of the name of that 650 * declaration, where the name of that declaration would occur if it is 651 * unnamed, or some keyword that introduces that particular declaration. 652 * The location of a reference is where that reference occurs within the 653 * source code. 654 */ 655CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 656 657/** 658 * \brief Retrieve the physical extent of the source construct referenced by 659 * the given cursor. 660 * 661 * The extent of a cursor starts with the file/line/column pointing at the 662 * first character within the source construct that the cursor refers to and 663 * ends with the last character withinin that source construct. For a 664 * declaration, the extent covers the declaration itself. For a reference, 665 * the extent covers the location of the reference (e.g., where the referenced 666 * entity was actually used). 667 */ 668CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 669 670/** 671 * @} 672 */ 673 674/** 675 * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 676 * 677 * These routines provide the ability to traverse the abstract syntax tree 678 * using cursors. 679 * 680 * @{ 681 */ 682 683/** 684 * \brief Describes how the traversal of the children of a particular 685 * cursor should proceed after visiting a particular child cursor. 686 * 687 * A value of this enumeration type should be returned by each 688 * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 689 */ 690enum CXChildVisitResult { 691 /** 692 * \brief Terminates the cursor traversal. 693 */ 694 CXChildVisit_Break, 695 /** 696 * \brief Continues the cursor traversal with the next sibling of 697 * the cursor just visited, without visiting its children. 698 */ 699 CXChildVisit_Continue, 700 /** 701 * \brief Recursively traverse the children of this cursor, using 702 * the same visitor and client data. 703 */ 704 CXChildVisit_Recurse 705}; 706 707/** 708 * \brief Visitor invoked for each cursor found by a traversal. 709 * 710 * This visitor function will be invoked for each cursor found by 711 * clang_visitCursorChildren(). Its first argument is the cursor being 712 * visited, its second argument is the parent visitor for that cursor, 713 * and its third argument is the client data provided to 714 * clang_visitCursorChildren(). 715 * 716 * The visitor should return one of the \c CXChildVisitResult values 717 * to direct clang_visitCursorChildren(). 718 */ 719typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 720 CXCursor parent, 721 CXClientData client_data); 722 723/** 724 * \brief Visit the children of a particular cursor. 725 * 726 * This function visits all the direct children of the given cursor, 727 * invoking the given \p visitor function with the cursors of each 728 * visited child. The traversal may be recursive, if the visitor returns 729 * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 730 * the visitor returns \c CXChildVisit_Break. 731 * 732 * \param tu the translation unit into which the cursor refers. 733 * 734 * \param parent the cursor whose child may be visited. All kinds of 735 * cursors can be visited, including invalid visitors (which, by 736 * definition, have no children). 737 * 738 * \param visitor the visitor function that will be invoked for each 739 * child of \p parent. 740 * 741 * \param client_data pointer data supplied by the client, which will 742 * be passed to the visitor each time it is invoked. 743 * 744 * \returns a non-zero value if the traversal was terminated 745 * prematurely by the visitor returning \c CXChildVisit_Break. 746 */ 747CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 748 CXCursorVisitor visitor, 749 CXClientData client_data); 750 751/** 752 * @} 753 */ 754 755/** 756 * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 757 * 758 * These routines provide the ability to determine references within and 759 * across translation units, by providing the names of the entities referenced 760 * by cursors, follow reference cursors to the declarations they reference, 761 * and associate declarations with their definitions. 762 * 763 * @{ 764 */ 765 766/** 767 * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 768 * by the given cursor. 769 * 770 * A Unified Symbol Resolution (USR) is a string that identifies a particular 771 * entity (function, class, variable, etc.) within a program. USRs can be 772 * compared across translation units to determine, e.g., when references in 773 * one translation refer to an entity defined in another translation unit. 774 */ 775CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 776 777/** 778 * \brief Retrieve a name for the entity referenced by this cursor. 779 */ 780CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 781 782/** \brief For a cursor that is a reference, retrieve a cursor representing the 783 * entity that it references. 784 * 785 * Reference cursors refer to other entities in the AST. For example, an 786 * Objective-C superclass reference cursor refers to an Objective-C class. 787 * This function produces the cursor for the Objective-C class from the 788 * cursor for the superclass reference. If the input cursor is a declaration or 789 * definition, it returns that declaration or definition unchanged. 790 * Othewise, returns the NULL cursor. 791 */ 792CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 793 794/** 795 * \brief For a cursor that is either a reference to or a declaration 796 * of some entity, retrieve a cursor that describes the definition of 797 * that entity. 798 * 799 * Some entities can be declared multiple times within a translation 800 * unit, but only one of those declarations can also be a 801 * definition. For example, given: 802 * 803 * \code 804 * int f(int, int); 805 * int g(int x, int y) { return f(x, y); } 806 * int f(int a, int b) { return a + b; } 807 * int f(int, int); 808 * \endcode 809 * 810 * there are three declarations of the function "f", but only the 811 * second one is a definition. The clang_getCursorDefinition() 812 * function will take any cursor pointing to a declaration of "f" 813 * (the first or fourth lines of the example) or a cursor referenced 814 * that uses "f" (the call to "f' inside "g") and will return a 815 * declaration cursor pointing to the definition (the second "f" 816 * declaration). 817 * 818 * If given a cursor for which there is no corresponding definition, 819 * e.g., because there is no definition of that entity within this 820 * translation unit, returns a NULL cursor. 821 */ 822CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 823 824/** 825 * \brief Determine whether the declaration pointed to by this cursor 826 * is also a definition of that entity. 827 */ 828CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 829 830/** 831 * @} 832 */ 833 834/** 835 * \defgroup CINDEX_DEBUG Debugging facilities 836 * 837 * These routines are used for testing and debugging, only, and should not 838 * be relied upon. 839 * 840 * @{ 841 */ 842 843/* for debug/testing */ 844CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); 845CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 846 const char **startBuf, 847 const char **endBuf, 848 unsigned *startLine, 849 unsigned *startColumn, 850 unsigned *endLine, 851 unsigned *endColumn); 852 853/** 854 * @} 855 */ 856 857/** 858 * \defgroup CINDEX_CODE_COMPLET Code completion 859 * 860 * Code completion involves taking an (incomplete) source file, along with 861 * knowledge of where the user is actively editing that file, and suggesting 862 * syntactically- and semantically-valid constructs that the user might want to 863 * use at that particular point in the source code. These data structures and 864 * routines provide support for code completion. 865 * 866 * @{ 867 */ 868 869/** 870 * \brief A semantic string that describes a code-completion result. 871 * 872 * A semantic string that describes the formatting of a code-completion 873 * result as a single "template" of text that should be inserted into the 874 * source buffer when a particular code-completion result is selected. 875 * Each semantic string is made up of some number of "chunks", each of which 876 * contains some text along with a description of what that text means, e.g., 877 * the name of the entity being referenced, whether the text chunk is part of 878 * the template, or whether it is a "placeholder" that the user should replace 879 * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 880 * description of the different kinds of chunks. 881 */ 882typedef void *CXCompletionString; 883 884/** 885 * \brief A single result of code completion. 886 */ 887typedef struct { 888 /** 889 * \brief The kind of entity that this completion refers to. 890 * 891 * The cursor kind will be a macro, keyword, or a declaration (one of the 892 * *Decl cursor kinds), describing the entity that the completion is 893 * referring to. 894 * 895 * \todo In the future, we would like to provide a full cursor, to allow 896 * the client to extract additional information from declaration. 897 */ 898 enum CXCursorKind CursorKind; 899 900 /** 901 * \brief The code-completion string that describes how to insert this 902 * code-completion result into the editing buffer. 903 */ 904 CXCompletionString CompletionString; 905} CXCompletionResult; 906 907/** 908 * \brief Describes a single piece of text within a code-completion string. 909 * 910 * Each "chunk" within a code-completion string (\c CXCompletionString) is 911 * either a piece of text with a specific "kind" that describes how that text 912 * should be interpreted by the client or is another completion string. 913 */ 914enum CXCompletionChunkKind { 915 /** 916 * \brief A code-completion string that describes "optional" text that 917 * could be a part of the template (but is not required). 918 * 919 * The Optional chunk is the only kind of chunk that has a code-completion 920 * string for its representation, which is accessible via 921 * \c clang_getCompletionChunkCompletionString(). The code-completion string 922 * describes an additional part of the template that is completely optional. 923 * For example, optional chunks can be used to describe the placeholders for 924 * arguments that match up with defaulted function parameters, e.g. given: 925 * 926 * \code 927 * void f(int x, float y = 3.14, double z = 2.71828); 928 * \endcode 929 * 930 * The code-completion string for this function would contain: 931 * - a TypedText chunk for "f". 932 * - a LeftParen chunk for "(". 933 * - a Placeholder chunk for "int x" 934 * - an Optional chunk containing the remaining defaulted arguments, e.g., 935 * - a Comma chunk for "," 936 * - a Placeholder chunk for "float x" 937 * - an Optional chunk containing the last defaulted argument: 938 * - a Comma chunk for "," 939 * - a Placeholder chunk for "double z" 940 * - a RightParen chunk for ")" 941 * 942 * There are many ways two handle Optional chunks. Two simple approaches are: 943 * - Completely ignore optional chunks, in which case the template for the 944 * function "f" would only include the first parameter ("int x"). 945 * - Fully expand all optional chunks, in which case the template for the 946 * function "f" would have all of the parameters. 947 */ 948 CXCompletionChunk_Optional, 949 /** 950 * \brief Text that a user would be expected to type to get this 951 * code-completion result. 952 * 953 * There will be exactly one "typed text" chunk in a semantic string, which 954 * will typically provide the spelling of a keyword or the name of a 955 * declaration that could be used at the current code point. Clients are 956 * expected to filter the code-completion results based on the text in this 957 * chunk. 958 */ 959 CXCompletionChunk_TypedText, 960 /** 961 * \brief Text that should be inserted as part of a code-completion result. 962 * 963 * A "text" chunk represents text that is part of the template to be 964 * inserted into user code should this particular code-completion result 965 * be selected. 966 */ 967 CXCompletionChunk_Text, 968 /** 969 * \brief Placeholder text that should be replaced by the user. 970 * 971 * A "placeholder" chunk marks a place where the user should insert text 972 * into the code-completion template. For example, placeholders might mark 973 * the function parameters for a function declaration, to indicate that the 974 * user should provide arguments for each of those parameters. The actual 975 * text in a placeholder is a suggestion for the text to display before 976 * the user replaces the placeholder with real code. 977 */ 978 CXCompletionChunk_Placeholder, 979 /** 980 * \brief Informative text that should be displayed but never inserted as 981 * part of the template. 982 * 983 * An "informative" chunk contains annotations that can be displayed to 984 * help the user decide whether a particular code-completion result is the 985 * right option, but which is not part of the actual template to be inserted 986 * by code completion. 987 */ 988 CXCompletionChunk_Informative, 989 /** 990 * \brief Text that describes the current parameter when code-completion is 991 * referring to function call, message send, or template specialization. 992 * 993 * A "current parameter" chunk occurs when code-completion is providing 994 * information about a parameter corresponding to the argument at the 995 * code-completion point. For example, given a function 996 * 997 * \code 998 * int add(int x, int y); 999 * \endcode 1000 * 1001 * and the source code \c add(, where the code-completion point is after the 1002 * "(", the code-completion string will contain a "current parameter" chunk 1003 * for "int x", indicating that the current argument will initialize that 1004 * parameter. After typing further, to \c add(17, (where the code-completion 1005 * point is after the ","), the code-completion string will contain a 1006 * "current paremeter" chunk to "int y". 1007 */ 1008 CXCompletionChunk_CurrentParameter, 1009 /** 1010 * \brief A left parenthesis ('('), used to initiate a function call or 1011 * signal the beginning of a function parameter list. 1012 */ 1013 CXCompletionChunk_LeftParen, 1014 /** 1015 * \brief A right parenthesis (')'), used to finish a function call or 1016 * signal the end of a function parameter list. 1017 */ 1018 CXCompletionChunk_RightParen, 1019 /** 1020 * \brief A left bracket ('['). 1021 */ 1022 CXCompletionChunk_LeftBracket, 1023 /** 1024 * \brief A right bracket (']'). 1025 */ 1026 CXCompletionChunk_RightBracket, 1027 /** 1028 * \brief A left brace ('{'). 1029 */ 1030 CXCompletionChunk_LeftBrace, 1031 /** 1032 * \brief A right brace ('}'). 1033 */ 1034 CXCompletionChunk_RightBrace, 1035 /** 1036 * \brief A left angle bracket ('<'). 1037 */ 1038 CXCompletionChunk_LeftAngle, 1039 /** 1040 * \brief A right angle bracket ('>'). 1041 */ 1042 CXCompletionChunk_RightAngle, 1043 /** 1044 * \brief A comma separator (','). 1045 */ 1046 CXCompletionChunk_Comma, 1047 /** 1048 * \brief Text that specifies the result type of a given result. 1049 * 1050 * This special kind of informative chunk is not meant to be inserted into 1051 * the text buffer. Rather, it is meant to illustrate the type that an 1052 * expression using the given completion string would have. 1053 */ 1054 CXCompletionChunk_ResultType, 1055 /** 1056 * \brief A colon (':'). 1057 */ 1058 CXCompletionChunk_Colon, 1059 /** 1060 * \brief A semicolon (';'). 1061 */ 1062 CXCompletionChunk_SemiColon, 1063 /** 1064 * \brief An '=' sign. 1065 */ 1066 CXCompletionChunk_Equal, 1067 /** 1068 * Horizontal space (' '). 1069 */ 1070 CXCompletionChunk_HorizontalSpace, 1071 /** 1072 * Vertical space ('\n'), after which it is generally a good idea to 1073 * perform indentation. 1074 */ 1075 CXCompletionChunk_VerticalSpace 1076}; 1077 1078/** 1079 * \brief Determine the kind of a particular chunk within a completion string. 1080 * 1081 * \param completion_string the completion string to query. 1082 * 1083 * \param chunk_number the 0-based index of the chunk in the completion string. 1084 * 1085 * \returns the kind of the chunk at the index \c chunk_number. 1086 */ 1087CINDEX_LINKAGE enum CXCompletionChunkKind 1088clang_getCompletionChunkKind(CXCompletionString completion_string, 1089 unsigned chunk_number); 1090 1091/** 1092 * \brief Retrieve the text associated with a particular chunk within a 1093 * completion string. 1094 * 1095 * \param completion_string the completion string to query. 1096 * 1097 * \param chunk_number the 0-based index of the chunk in the completion string. 1098 * 1099 * \returns the text associated with the chunk at index \c chunk_number. 1100 */ 1101CINDEX_LINKAGE const char * 1102clang_getCompletionChunkText(CXCompletionString completion_string, 1103 unsigned chunk_number); 1104 1105/** 1106 * \brief Retrieve the completion string associated with a particular chunk 1107 * within a completion string. 1108 * 1109 * \param completion_string the completion string to query. 1110 * 1111 * \param chunk_number the 0-based index of the chunk in the completion string. 1112 * 1113 * \returns the completion string associated with the chunk at index 1114 * \c chunk_number, or NULL if that chunk is not represented by a completion 1115 * string. 1116 */ 1117CINDEX_LINKAGE CXCompletionString 1118clang_getCompletionChunkCompletionString(CXCompletionString completion_string, 1119 unsigned chunk_number); 1120 1121/** 1122 * \brief Retrieve the number of chunks in the given code-completion string. 1123 */ 1124CINDEX_LINKAGE unsigned 1125clang_getNumCompletionChunks(CXCompletionString completion_string); 1126 1127/** 1128 * \brief Contains the results of code-completion. 1129 * 1130 * This data structure contains the results of code completion, as 1131 * produced by \c clang_codeComplete. Its contents must be freed by 1132 * \c clang_disposeCodeCompleteResults. 1133 */ 1134typedef struct { 1135 /** 1136 * \brief The code-completion results. 1137 */ 1138 CXCompletionResult *Results; 1139 1140 /** 1141 * \brief The number of code-completion results stored in the 1142 * \c Results array. 1143 */ 1144 unsigned NumResults; 1145} CXCodeCompleteResults; 1146 1147/** 1148 * \brief Perform code completion at a given location in a source file. 1149 * 1150 * This function performs code completion at a particular file, line, and 1151 * column within source code, providing results that suggest potential 1152 * code snippets based on the context of the completion. The basic model 1153 * for code completion is that Clang will parse a complete source file, 1154 * performing syntax checking up to the location where code-completion has 1155 * been requested. At that point, a special code-completion token is passed 1156 * to the parser, which recognizes this token and determines, based on the 1157 * current location in the C/Objective-C/C++ grammar and the state of 1158 * semantic analysis, what completions to provide. These completions are 1159 * returned via a new \c CXCodeCompleteResults structure. 1160 * 1161 * Code completion itself is meant to be triggered by the client when the 1162 * user types punctuation characters or whitespace, at which point the 1163 * code-completion location will coincide with the cursor. For example, if \c p 1164 * is a pointer, code-completion might be triggered after the "-" and then 1165 * after the ">" in \c p->. When the code-completion location is afer the ">", 1166 * the completion results will provide, e.g., the members of the struct that 1167 * "p" points to. The client is responsible for placing the cursor at the 1168 * beginning of the token currently being typed, then filtering the results 1169 * based on the contents of the token. For example, when code-completing for 1170 * the expression \c p->get, the client should provide the location just after 1171 * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 1172 * client can filter the results based on the current token text ("get"), only 1173 * showing those results that start with "get". The intent of this interface 1174 * is to separate the relatively high-latency acquisition of code-completion 1175 * results from the filtering of results on a per-character basis, which must 1176 * have a lower latency. 1177 * 1178 * \param CIdx the \c CXIndex instance that will be used to perform code 1179 * completion. 1180 * 1181 * \param source_filename the name of the source file that should be parsed to 1182 * perform code-completion. This source file must be the same as or include the 1183 * filename described by \p complete_filename, or no code-completion results 1184 * will be produced. NOTE: One can also specify NULL for this argument if the 1185 * source file is included in command_line_args. 1186 * 1187 * \param num_command_line_args the number of command-line arguments stored in 1188 * \p command_line_args. 1189 * 1190 * \param command_line_args the command-line arguments to pass to the Clang 1191 * compiler to build the given source file. This should include all of the 1192 * necessary include paths, language-dialect switches, precompiled header 1193 * includes, etc., but should not include any information specific to 1194 * code completion. 1195 * 1196 * \param num_unsaved_files the number of unsaved file entries in \p 1197 * unsaved_files. 1198 * 1199 * \param unsaved_files the files that have not yet been saved to disk 1200 * but may be required for code completion, including the contents of 1201 * those files. 1202 * 1203 * \param complete_filename the name of the source file where code completion 1204 * should be performed. In many cases, this name will be the same as the 1205 * source filename. However, the completion filename may also be a file 1206 * included by the source file, which is required when producing 1207 * code-completion results for a header. 1208 * 1209 * \param complete_line the line at which code-completion should occur. 1210 * 1211 * \param complete_column the column at which code-completion should occur. 1212 * Note that the column should point just after the syntactic construct that 1213 * initiated code completion, and not in the middle of a lexical token. 1214 * 1215 * \returns if successful, a new CXCodeCompleteResults structure 1216 * containing code-completion results, which should eventually be 1217 * freed with \c clang_disposeCodeCompleteResults(). If code 1218 * completion fails, returns NULL. 1219 */ 1220CINDEX_LINKAGE 1221CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 1222 const char *source_filename, 1223 int num_command_line_args, 1224 const char **command_line_args, 1225 unsigned num_unsaved_files, 1226 struct CXUnsavedFile *unsaved_files, 1227 const char *complete_filename, 1228 unsigned complete_line, 1229 unsigned complete_column); 1230 1231/** 1232 * \brief Free the given set of code-completion results. 1233 */ 1234CINDEX_LINKAGE 1235void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 1236 1237/** 1238 * @} 1239 */ 1240 1241 1242/** 1243 * \defgroup CINDEX_MISC Miscellaneous utility functions 1244 * 1245 * @{ 1246 */ 1247 1248CINDEX_LINKAGE const char *clang_getClangVersion(); 1249 1250/** 1251 * @} 1252 */ 1253 1254/** 1255 * @} 1256 */ 1257 1258#ifdef __cplusplus 1259} 1260#endif 1261#endif 1262 1263