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