Index.h revision 249423
118334Speter/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\ 252284Sobrien|* *| 318334Speter|* The LLVM Compiler Infrastructure *| 418334Speter|* *| 518334Speter|* This file is distributed under the University of Illinois Open Source *| 618334Speter|* License. See LICENSE.TXT for details. *| 718334Speter|* *| 818334Speter|*===----------------------------------------------------------------------===*| 918334Speter|* *| 1018334Speter|* This header provides a public inferface to a Clang library for extracting *| 1118334Speter|* high-level symbol information from source files without exposing the full *| 1218334Speter|* Clang C++ API. *| 1318334Speter|* *| 1418334Speter\*===----------------------------------------------------------------------===*/ 1518334Speter 1618334Speter#ifndef CLANG_C_INDEX_H 1718334Speter#define CLANG_C_INDEX_H 1818334Speter 1918334Speter#include <sys/stat.h> 2018334Speter#include <time.h> 2118334Speter#include <stdio.h> 2218334Speter 2318334Speter#include "clang-c/Platform.h" 2418334Speter#include "clang-c/CXString.h" 2518334Speter 2618334Speter/** 2718334Speter * \brief The version constants for the libclang API. 2818334Speter * CINDEX_VERSION_MINOR should increase when there are API additions. 2918334Speter * CINDEX_VERSION_MAJOR is intended for "major" source/ABI breaking changes. 3018334Speter * 3118334Speter * The policy about the libclang API was always to keep it source and ABI 3218334Speter * compatible, thus CINDEX_VERSION_MAJOR is expected to remain stable. 3318334Speter */ 3418334Speter#define CINDEX_VERSION_MAJOR 0 3518334Speter#define CINDEX_VERSION_MINOR 15 3618334Speter 3718334Speter#define CINDEX_VERSION_ENCODE(major, minor) ( \ 3818334Speter ((major) * 10000) \ 3918334Speter + ((minor) * 1)) 4018334Speter 4118334Speter#define CINDEX_VERSION CINDEX_VERSION_ENCODE( \ 4218334Speter CINDEX_VERSION_MAJOR, \ 4318334Speter CINDEX_VERSION_MINOR ) 4418334Speter 4518334Speter#define CINDEX_VERSION_STRINGIZE_(major, minor) \ 4618334Speter #major"."#minor 4718334Speter#define CINDEX_VERSION_STRINGIZE(major, minor) \ 4818334Speter CINDEX_VERSION_STRINGIZE_(major, minor) 4918334Speter 5018334Speter#define CINDEX_VERSION_STRING CINDEX_VERSION_STRINGIZE( \ 5118334Speter CINDEX_VERSION_MAJOR, \ 5218334Speter CINDEX_VERSION_MINOR) 5318334Speter 5418334Speter#ifdef __cplusplus 5518334Speterextern "C" { 5618334Speter#endif 5718334Speter 5818334Speter/** \defgroup CINDEX libclang: C Interface to Clang 5918334Speter * 6018334Speter * The C Interface to Clang provides a relatively small API that exposes 6118334Speter * facilities for parsing source code into an abstract syntax tree (AST), 6218334Speter * loading already-parsed ASTs, traversing the AST, associating 6318334Speter * physical source locations with elements within the AST, and other 6418334Speter * facilities that support Clang-based development tools. 6518334Speter * 6618334Speter * This C interface to Clang will never provide all of the information 6718334Speter * representation stored in Clang's C++ AST, nor should it: the intent is to 6818334Speter * maintain an API that is relatively stable from one release to the next, 6918334Speter * providing only the basic functionality needed to support development tools. 7018334Speter * 7118334Speter * To avoid namespace pollution, data types are prefixed with "CX" and 7218334Speter * functions are prefixed with "clang_". 7318334Speter * 7418334Speter * @{ 7518334Speter */ 7618334Speter 7718334Speter/** 7818334Speter * \brief An "index" that consists of a set of translation units that would 7918334Speter * typically be linked together into an executable or library. 8018334Speter */ 8118334Spetertypedef void *CXIndex; 8218334Speter 8318334Speter/** 8418334Speter * \brief A single translation unit, which resides in an index. 8518334Speter */ 8618334Spetertypedef struct CXTranslationUnitImpl *CXTranslationUnit; 8718334Speter 8818334Speter/** 8918334Speter * \brief Opaque pointer representing client data that will be passed through 9018334Speter * to various callbacks and visitors. 9118334Speter */ 9218334Spetertypedef void *CXClientData; 9318334Speter 9418334Speter/** 9518334Speter * \brief Provides the contents of a file that has not yet been saved to disk. 9618334Speter * 9718334Speter * Each CXUnsavedFile instance provides the name of a file on the 9818334Speter * system along with the current contents of that file that have not 9918334Speter * yet been saved to disk. 10018334Speter */ 10118334Speterstruct CXUnsavedFile { 10218334Speter /** 10318334Speter * \brief The file whose contents have not yet been saved. 10418334Speter * 10518334Speter * This file must already exist in the file system. 10618334Speter */ 10718334Speter const char *Filename; 10818334Speter 10918334Speter /** 11018334Speter * \brief A buffer containing the unsaved contents of this file. 11118334Speter */ 11218334Speter const char *Contents; 11318334Speter 11418334Speter /** 11518334Speter * \brief The length of the unsaved contents of this buffer. 11618334Speter */ 11718334Speter unsigned long Length; 11818334Speter}; 11918334Speter 12018334Speter/** 12118334Speter * \brief Describes the availability of a particular entity, which indicates 12218334Speter * whether the use of this entity will result in a warning or error due to 12318334Speter * it being deprecated or unavailable. 12418334Speter */ 12518334Speterenum CXAvailabilityKind { 12618334Speter /** 12718334Speter * \brief The entity is available. 12818334Speter */ 12918334Speter CXAvailability_Available, 13018334Speter /** 13118334Speter * \brief The entity is available, but has been deprecated (and its use is 13218334Speter * not recommended). 13318334Speter */ 13418334Speter CXAvailability_Deprecated, 13518334Speter /** 13618334Speter * \brief The entity is not available; any use of it will be an error. 13718334Speter */ 13818334Speter CXAvailability_NotAvailable, 13918334Speter /** 14018334Speter * \brief The entity is available, but not accessible; any use of it will be 14118334Speter * an error. 14218334Speter */ 14318334Speter CXAvailability_NotAccessible 14418334Speter}; 14518334Speter 14618334Speter/** 14718334Speter * \brief Describes a version number of the form major.minor.subminor. 14818334Speter */ 14918334Spetertypedef struct CXVersion { 15018334Speter /** 15118334Speter * \brief The major version number, e.g., the '10' in '10.7.3'. A negative 15218334Speter * value indicates that there is no version number at all. 15318334Speter */ 15450397Sobrien int Major; 15518334Speter /** 15618334Speter * \brief The minor version number, e.g., the '7' in '10.7.3'. This value 15718334Speter * will be negative if no minor version number was provided, e.g., for 15818334Speter * version '10'. 15918334Speter */ 16018334Speter int Minor; 16150397Sobrien /** 16252284Sobrien * \brief The subminor version number, e.g., the '3' in '10.7.3'. This value 16350397Sobrien * will be negative if no minor or subminor version number was provided, 16452284Sobrien * e.g., in version '10' or '10.7'. 16518334Speter */ 16618334Speter int Subminor; 16718334Speter} CXVersion; 16818334Speter 16918334Speter/** 17018334Speter * \brief Provides a shared context for creating translation units. 17118334Speter * 17218334Speter * It provides two options: 17318334Speter * 17418334Speter * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 17518334Speter * declarations (when loading any new translation units). A "local" declaration 17618334Speter * is one that belongs in the translation unit itself and not in a precompiled 17718334Speter * header that was used by the translation unit. If zero, all declarations 17818334Speter * will be enumerated. 17918334Speter * 18018334Speter * Here is an example: 18118334Speter * 18218334Speter * \code 18318334Speter * // excludeDeclsFromPCH = 1, displayDiagnostics=1 18418334Speter * Idx = clang_createIndex(1, 1); 18518334Speter * 18618334Speter * // IndexTest.pch was produced with the following command: 18718334Speter * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 18818334Speter * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 18918334Speter * 19018334Speter * // This will load all the symbols from 'IndexTest.pch' 19118334Speter * clang_visitChildren(clang_getTranslationUnitCursor(TU), 19218334Speter * TranslationUnitVisitor, 0); 19318334Speter * clang_disposeTranslationUnit(TU); 19418334Speter * 19518334Speter * // This will load all the symbols from 'IndexTest.c', excluding symbols 19618334Speter * // from 'IndexTest.pch'. 19718334Speter * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch" }; 19818334Speter * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args, 19918334Speter * 0, 0); 20018334Speter * clang_visitChildren(clang_getTranslationUnitCursor(TU), 20118334Speter * TranslationUnitVisitor, 0); 20218334Speter * clang_disposeTranslationUnit(TU); 20318334Speter * \endcode 20418334Speter * 20518334Speter * This process of creating the 'pch', loading it separately, and using it (via 20618334Speter * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 20718334Speter * (which gives the indexer the same performance benefit as the compiler). 20818334Speter */ 20918334SpeterCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 21018334Speter int displayDiagnostics); 21118334Speter 21218334Speter/** 21350397Sobrien * \brief Destroy the given index. 21418334Speter * 21518334Speter * The index must not be destroyed until all of the translation units created 21652284Sobrien * within that index have been destroyed. 21752284Sobrien */ 21852284SobrienCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 21952284Sobrien 22052284Sobrientypedef enum { 22152284Sobrien /** 22252284Sobrien * \brief Used to indicate that no special CXIndex options are needed. 22352284Sobrien */ 22418334Speter CXGlobalOpt_None = 0x0, 22518334Speter 22618334Speter /** 22718334Speter * \brief Used to indicate that threads that libclang creates for indexing 22818334Speter * purposes should use background priority. 22918334Speter * 23018334Speter * Affects #clang_indexSourceFile, #clang_indexTranslationUnit, 23118334Speter * #clang_parseTranslationUnit, #clang_saveTranslationUnit. 23250397Sobrien */ 23318334Speter CXGlobalOpt_ThreadBackgroundPriorityForIndexing = 0x1, 23452284Sobrien 23518334Speter /** 23652284Sobrien * \brief Used to indicate that threads that libclang creates for editing 23752284Sobrien * purposes should use background priority. 23852284Sobrien * 23952284Sobrien * Affects #clang_reparseTranslationUnit, #clang_codeCompleteAt, 24052284Sobrien * #clang_annotateTokens 24152284Sobrien */ 24252284Sobrien CXGlobalOpt_ThreadBackgroundPriorityForEditing = 0x2, 24352284Sobrien 24452284Sobrien /** 24552284Sobrien * \brief Used to indicate that all threads that libclang creates should use 24652284Sobrien * background priority. 24752284Sobrien */ 24852284Sobrien CXGlobalOpt_ThreadBackgroundPriorityForAll = 24952284Sobrien CXGlobalOpt_ThreadBackgroundPriorityForIndexing | 25052284Sobrien CXGlobalOpt_ThreadBackgroundPriorityForEditing 25152284Sobrien 25218334Speter} CXGlobalOptFlags; 25318334Speter 25418334Speter/** 25518334Speter * \brief Sets general options associated with a CXIndex. 25650397Sobrien * 25750397Sobrien * For example: 25850397Sobrien * \code 25950397Sobrien * CXIndex idx = ...; 26050397Sobrien * clang_CXIndex_setGlobalOptions(idx, 26150397Sobrien * clang_CXIndex_getGlobalOptions(idx) | 26252284Sobrien * CXGlobalOpt_ThreadBackgroundPriorityForIndexing); 26350397Sobrien * \endcode 26450397Sobrien * 26552284Sobrien * \param options A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags. 26650397Sobrien */ 26750397SobrienCINDEX_LINKAGE void clang_CXIndex_setGlobalOptions(CXIndex, unsigned options); 26850397Sobrien 26950397Sobrien/** 27050397Sobrien * \brief Gets the general options associated with a CXIndex. 27150397Sobrien * 27250397Sobrien * \returns A bitmask of options, a bitwise OR of CXGlobalOpt_XXX flags that 27350397Sobrien * are associated with the given CXIndex object. 27450397Sobrien */ 27550397SobrienCINDEX_LINKAGE unsigned clang_CXIndex_getGlobalOptions(CXIndex); 27650397Sobrien 27750397Sobrien/** 27850397Sobrien * \defgroup CINDEX_FILES File manipulation routines 27950397Sobrien * 28052284Sobrien * @{ 28150397Sobrien */ 28250397Sobrien 28350397Sobrien/** 28450397Sobrien * \brief A particular source file that is part of a translation unit. 28550397Sobrien */ 28650397Sobrientypedef void *CXFile; 28750397Sobrien 28852284Sobrien 28918334Speter/** 29052284Sobrien * \brief Retrieve the complete file and path name of the given file. 29152284Sobrien */ 29252284SobrienCINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); 29352284Sobrien 29452284Sobrien/** 29552284Sobrien * \brief Retrieve the last modification time of the given file. 29652284Sobrien */ 29752284SobrienCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 29852284Sobrien 29952284Sobrien/** 30052284Sobrien * \brief Uniquely identifies a CXFile, that refers to the same underlying file, 30152284Sobrien * across an indexing session. 30252284Sobrien */ 30352284Sobrientypedef struct { 30452284Sobrien unsigned long long data[3]; 30552284Sobrien} CXFileUniqueID; 30652284Sobrien 30752284Sobrien/** 30852284Sobrien * \brief Retrieve the unique ID for the given \c file. 30952284Sobrien * 31052284Sobrien * \param file the file to get the ID for. 31152284Sobrien * \param outID stores the returned CXFileUniqueID. 31252284Sobrien * \returns If there was a failure getting the unique ID, returns non-zero, 31352284Sobrien * otherwise returns 0. 31452284Sobrien*/ 31552284SobrienCINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID); 31652284Sobrien 31752284Sobrien/** 31852284Sobrien * \brief Determine whether the given header is guarded against 31952284Sobrien * multiple inclusions, either with the conventional 32052284Sobrien * \#ifndef/\#define/\#endif macro guards or with \#pragma once. 32152284Sobrien */ 32252284SobrienCINDEX_LINKAGE unsigned 32352284Sobrienclang_isFileMultipleIncludeGuarded(CXTranslationUnit tu, CXFile file); 32452284Sobrien 32552284Sobrien/** 32652284Sobrien * \brief Retrieve a file handle within the given translation unit. 32752284Sobrien * 32852284Sobrien * \param tu the translation unit 32952284Sobrien * 33018334Speter * \param file_name the name of the file. 33118334Speter * 33218334Speter * \returns the file handle for the named file in the translation unit \p tu, 33318334Speter * or a NULL file handle if the file was not a part of this translation unit. 33418334Speter */ 33518334SpeterCINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, 33618334Speter const char *file_name); 33718334Speter 33818334Speter/** 33918334Speter * @} 34018334Speter */ 34118334Speter 34218334Speter/** 34318334Speter * \defgroup CINDEX_LOCATIONS Physical source locations 34418334Speter * 34518334Speter * Clang represents physical source locations in its abstract syntax tree in 34618334Speter * great detail, with file, line, and column information for the majority of 34718334Speter * the tokens parsed in the source code. These data types and functions are 34818334Speter * used to represent source location information, either for a particular 34918334Speter * point in the program or for a range of points in the program, and extract 35018334Speter * specific location information from those data types. 35118334Speter * 35218334Speter * @{ 35318334Speter */ 35418334Speter 35518334Speter/** 35618334Speter * \brief Identifies a specific source location within a translation 35718334Speter * unit. 35818334Speter * 35918334Speter * Use clang_getExpansionLocation() or clang_getSpellingLocation() 36018334Speter * to map a source location to a particular file, line, and column. 36118334Speter */ 36218334Spetertypedef struct { 36318334Speter const void *ptr_data[2]; 36418334Speter unsigned int_data; 36518334Speter} CXSourceLocation; 36650397Sobrien 36750397Sobrien/** 36850397Sobrien * \brief Identifies a half-open character range in the source code. 36950397Sobrien * 37050397Sobrien * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 37150397Sobrien * starting and end locations from a source range, respectively. 37250397Sobrien */ 37318334Spetertypedef struct { 37418334Speter const void *ptr_data[2]; 37518334Speter unsigned begin_int_data; 37618334Speter unsigned end_int_data; 37718334Speter} CXSourceRange; 37818334Speter 37918334Speter/** 38050397Sobrien * \brief Retrieve a NULL (invalid) source location. 38150397Sobrien */ 38250397SobrienCINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); 38350397Sobrien 38450397Sobrien/** 38550397Sobrien * \brief Determine whether two source locations, which must refer into 38650397Sobrien * the same translation unit, refer to exactly the same point in the source 38750397Sobrien * code. 38850397Sobrien * 38950397Sobrien * \returns non-zero if the source locations refer to the same location, zero 39050397Sobrien * if they refer to different locations. 39150397Sobrien */ 39250397SobrienCINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 39350397Sobrien CXSourceLocation loc2); 39450397Sobrien 39550397Sobrien/** 39650397Sobrien * \brief Retrieves the source location associated with a given file/line/column 39750397Sobrien * in a particular translation unit. 39850397Sobrien */ 39950397SobrienCINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, 40050397Sobrien CXFile file, 40150397Sobrien unsigned line, 40250397Sobrien unsigned column); 40350397Sobrien/** 40450397Sobrien * \brief Retrieves the source location associated with a given character offset 40550397Sobrien * in a particular translation unit. 40618334Speter */ 40718334SpeterCINDEX_LINKAGE CXSourceLocation clang_getLocationForOffset(CXTranslationUnit tu, 40818334Speter CXFile file, 40918334Speter unsigned offset); 41018334Speter 41118334Speter/** 41218334Speter * \brief Retrieve a NULL (invalid) source range. 41318334Speter */ 41418334SpeterCINDEX_LINKAGE CXSourceRange clang_getNullRange(void); 41518334Speter 41618334Speter/** 41718334Speter * \brief Retrieve a source range given the beginning and ending source 41818334Speter * locations. 41918334Speter */ 42018334SpeterCINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 42118334Speter CXSourceLocation end); 42218334Speter 42318334Speter/** 42418334Speter * \brief Determine whether two ranges are equivalent. 42518334Speter * 42618334Speter * \returns non-zero if the ranges are the same, zero if they differ. 42718334Speter */ 42818334SpeterCINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, 42918334Speter CXSourceRange range2); 43018334Speter 43118334Speter/** 43218334Speter * \brief Returns non-zero if \p range is null. 43318334Speter */ 43418334SpeterCINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); 43518334Speter 43618334Speter/** 43718334Speter * \brief Retrieve the file, line, column, and offset represented by 43818334Speter * the given source location. 43918334Speter * 44018334Speter * If the location refers into a macro expansion, retrieves the 44118334Speter * location of the macro expansion. 44218334Speter * 44318334Speter * \param location the location within a source file that will be decomposed 44418334Speter * into its parts. 44518334Speter * 44618334Speter * \param file [out] if non-NULL, will be set to the file to which the given 44718334Speter * source location points. 44818334Speter * 44918334Speter * \param line [out] if non-NULL, will be set to the line to which the given 45018334Speter * source location points. 45118334Speter * 45218334Speter * \param column [out] if non-NULL, will be set to the column to which the given 45318334Speter * source location points. 45418334Speter * 45518334Speter * \param offset [out] if non-NULL, will be set to the offset into the 45618334Speter * buffer to which the given source location points. 45718334Speter */ 45852284SobrienCINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, 45952284Sobrien CXFile *file, 46052284Sobrien unsigned *line, 46152284Sobrien unsigned *column, 46218334Speter unsigned *offset); 46318334Speter 46418334Speter/** 46550397Sobrien * \brief Retrieve the file, line, column, and offset represented by 46618334Speter * the given source location, as specified in a # line directive. 46718334Speter * 46818334Speter * Example: given the following source code in a file somefile.c 46918334Speter * 47018334Speter * \code 47118334Speter * #123 "dummy.c" 1 47218334Speter * 47318334Speter * static int func(void) 47418334Speter * { 47518334Speter * return 0; 47618334Speter * } 47718334Speter * \endcode 47850397Sobrien * 47918334Speter * the location information returned by this function would be 48018334Speter * 48150397Sobrien * File: dummy.c Line: 124 Column: 12 48218334Speter * 48318334Speter * whereas clang_getExpansionLocation would have returned 48418334Speter * 48518334Speter * File: somefile.c Line: 3 Column: 12 48618334Speter * 48718334Speter * \param location the location within a source file that will be decomposed 48818334Speter * into its parts. 48918334Speter * 49050397Sobrien * \param filename [out] if non-NULL, will be set to the filename of the 49118334Speter * source location. Note that filenames returned will be for "virtual" files, 49218334Speter * which don't necessarily exist on the machine running clang - e.g. when 49318334Speter * parsing preprocessed output obtained from a different environment. If 49418334Speter * a non-NULL value is passed in, remember to dispose of the returned value 49518334Speter * using \c clang_disposeString() once you've finished with it. For an invalid 49618334Speter * source location, an empty string is returned. 49718334Speter * 49818334Speter * \param line [out] if non-NULL, will be set to the line number of the 49918334Speter * source location. For an invalid source location, zero is returned. 50018334Speter * 50118334Speter * \param column [out] if non-NULL, will be set to the column number of the 50218334Speter * source location. For an invalid source location, zero is returned. 50318334Speter */ 50418334SpeterCINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, 50518334Speter CXString *filename, 50618334Speter unsigned *line, 50718334Speter unsigned *column); 50818334Speter 50918334Speter/** 51018334Speter * \brief Legacy API to retrieve the file, line, column, and offset represented 51118334Speter * by the given source location. 51218334Speter * 51318334Speter * This interface has been replaced by the newer interface 51418334Speter * #clang_getExpansionLocation(). See that interface's documentation for 51518334Speter * details. 51650397Sobrien */ 51718334SpeterCINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 51818334Speter CXFile *file, 51918334Speter unsigned *line, 52018334Speter unsigned *column, 52118334Speter unsigned *offset); 52252284Sobrien 52318334Speter/** 52418334Speter * \brief Retrieve the file, line, column, and offset represented by 52518334Speter * the given source location. 52618334Speter * 52718334Speter * If the location refers into a macro instantiation, return where the 52850397Sobrien * location was originally spelled in the source file. 52918334Speter * 53018334Speter * \param location the location within a source file that will be decomposed 53118334Speter * into its parts. 53252284Sobrien * 53318334Speter * \param file [out] if non-NULL, will be set to the file to which the given 53418334Speter * source location points. 53518334Speter * 53618334Speter * \param line [out] if non-NULL, will be set to the line to which the given 53718334Speter * source location points. 53818334Speter * 53918334Speter * \param column [out] if non-NULL, will be set to the column to which the given 54018334Speter * source location points. 54118334Speter * 54218334Speter * \param offset [out] if non-NULL, will be set to the offset into the 54318334Speter * buffer to which the given source location points. 54418334Speter */ 54518334SpeterCINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, 54652284Sobrien CXFile *file, 54752284Sobrien unsigned *line, 54852284Sobrien unsigned *column, 54952284Sobrien unsigned *offset); 55018334Speter 55150397Sobrien/** 55218334Speter * \brief Retrieve the file, line, column, and offset represented by 55318334Speter * the given source location. 55418334Speter * 55518334Speter * If the location refers into a macro expansion, return where the macro was 55618334Speter * expanded or where the macro argument was written, if the location points at 55750397Sobrien * a macro argument. 55818334Speter * 55918334Speter * \param location the location within a source file that will be decomposed 56018334Speter * into its parts. 56118334Speter * 56218334Speter * \param file [out] if non-NULL, will be set to the file to which the given 56318334Speter * source location points. 56418334Speter * 56518334Speter * \param line [out] if non-NULL, will be set to the line to which the given 56618334Speter * source location points. 56718334Speter * 56818334Speter * \param column [out] if non-NULL, will be set to the column to which the given 56952284Sobrien * source location points. 57018334Speter * 57118334Speter * \param offset [out] if non-NULL, will be set to the offset into the 57218334Speter * buffer to which the given source location points. 57318334Speter */ 57418334SpeterCINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, 57518334Speter CXFile *file, 57650397Sobrien unsigned *line, 57718334Speter unsigned *column, 57818334Speter unsigned *offset); 57918334Speter 58018334Speter/** 58118334Speter * \brief Retrieve a source location representing the first character within a 58218334Speter * source range. 58318334Speter */ 58418334SpeterCINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 58552284Sobrien 58652284Sobrien/** 58718334Speter * \brief Retrieve a source location representing the last character within a 58818334Speter * source range. 58918334Speter */ 59018334SpeterCINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 59150397Sobrien 59218334Speter/** 59318334Speter * @} 59418334Speter */ 59518334Speter 59618334Speter/** 59718334Speter * \defgroup CINDEX_DIAG Diagnostic reporting 59818334Speter * 59918334Speter * @{ 60018334Speter */ 60118334Speter 60218334Speter/** 60318334Speter * \brief Describes the severity of a particular diagnostic. 60418334Speter */ 60518334Speterenum CXDiagnosticSeverity { 60618334Speter /** 60718334Speter * \brief A diagnostic that has been suppressed, e.g., by a command-line 60818334Speter * option. 60950397Sobrien */ 61050397Sobrien CXDiagnostic_Ignored = 0, 61150397Sobrien 61250397Sobrien /** 61318334Speter * \brief This diagnostic is a note that should be attached to the 61450397Sobrien * previous (non-note) diagnostic. 61550397Sobrien */ 61618334Speter CXDiagnostic_Note = 1, 61718334Speter 61818334Speter /** 61918334Speter * \brief This diagnostic indicates suspicious code that may not be 62018334Speter * wrong. 62118334Speter */ 62218334Speter CXDiagnostic_Warning = 2, 62318334Speter 62418334Speter /** 62518334Speter * \brief This diagnostic indicates that the code is ill-formed. 62618334Speter */ 62718334Speter CXDiagnostic_Error = 3, 62818334Speter 62918334Speter /** 63018334Speter * \brief This diagnostic indicates that the code is ill-formed such 63118334Speter * that future parser recovery is unlikely to produce useful 63218334Speter * results. 63318334Speter */ 63418334Speter CXDiagnostic_Fatal = 4 63518334Speter}; 63618334Speter 63718334Speter/** 63818334Speter * \brief A single diagnostic, containing the diagnostic's severity, 63918334Speter * location, text, source ranges, and fix-it hints. 64018334Speter */ 64118334Spetertypedef void *CXDiagnostic; 64218334Speter 64318334Speter/** 64418334Speter * \brief A group of CXDiagnostics. 64550397Sobrien */ 64618334Spetertypedef void *CXDiagnosticSet; 64718334Speter 64818334Speter/** 64918334Speter * \brief Determine the number of diagnostics in a CXDiagnosticSet. 65018334Speter */ 65118334SpeterCINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); 65218334Speter 65318334Speter/** 65418334Speter * \brief Retrieve a diagnostic associated with the given CXDiagnosticSet. 65518334Speter * 65650397Sobrien * \param Diags the CXDiagnosticSet to query. 65718334Speter * \param Index the zero-based diagnostic number to retrieve. 65818334Speter * 65918334Speter * \returns the requested diagnostic. This diagnostic must be freed 66018334Speter * via a call to \c clang_disposeDiagnostic(). 66118334Speter */ 66218334SpeterCINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, 66318334Speter unsigned Index); 66418334Speter 66518334Speter 66618334Speter/** 66718334Speter * \brief Describes the kind of error that occurred (if any) in a call to 66818334Speter * \c clang_loadDiagnostics. 66918334Speter */ 67018334Speterenum CXLoadDiag_Error { 67118334Speter /** 67218334Speter * \brief Indicates that no error occurred. 67318334Speter */ 67418334Speter CXLoadDiag_None = 0, 67552284Sobrien 67618334Speter /** 67718334Speter * \brief Indicates that an unknown error occurred while attempting to 67818334Speter * deserialize diagnostics. 67918334Speter */ 68018334Speter CXLoadDiag_Unknown = 1, 68150397Sobrien 68218334Speter /** 68318334Speter * \brief Indicates that the file containing the serialized diagnostics 68452284Sobrien * could not be opened. 68518334Speter */ 68618334Speter CXLoadDiag_CannotLoad = 2, 68718334Speter 68818334Speter /** 68918334Speter * \brief Indicates that the serialized diagnostics file is invalid or 69018334Speter * corrupt. 69118334Speter */ 69218334Speter CXLoadDiag_InvalidFile = 3 69318334Speter}; 69418334Speter 69552284Sobrien/** 69618334Speter * \brief Deserialize a set of diagnostics from a Clang diagnostics bitcode 69718334Speter * file. 69852284Sobrien * 69918334Speter * \param file The name of the file to deserialize. 70018334Speter * \param error A pointer to a enum value recording if there was a problem 70118334Speter * deserializing the diagnostics. 70252284Sobrien * \param errorString A pointer to a CXString for recording the error string 70352284Sobrien * if the file was not successfully loaded. 70452284Sobrien * 70518334Speter * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These 70652284Sobrien * diagnostics should be released using clang_disposeDiagnosticSet(). 70752284Sobrien */ 70852284SobrienCINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(const char *file, 70952284Sobrien enum CXLoadDiag_Error *error, 71052284Sobrien CXString *errorString); 71152284Sobrien 71252284Sobrien/** 71352284Sobrien * \brief Release a CXDiagnosticSet and all of its contained diagnostics. 71452284Sobrien */ 71552284SobrienCINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); 71652284Sobrien 71752284Sobrien/** 71852284Sobrien * \brief Retrieve the child diagnostics of a CXDiagnostic. 71952284Sobrien * 72050397Sobrien * This CXDiagnosticSet does not need to be released by 72152284Sobrien * clang_diposeDiagnosticSet. 72252284Sobrien */ 72352284SobrienCINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); 72452284Sobrien 72518334Speter/** 72618334Speter * \brief Determine the number of diagnostics produced for the given 72718334Speter * translation unit. 72818334Speter */ 72918334SpeterCINDEX_LINKAGE unsigned clang_getNumDiagnostics(CXTranslationUnit Unit); 73018334Speter 73118334Speter/** 73252284Sobrien * \brief Retrieve a diagnostic associated with the given translation unit. 73318334Speter * 73418334Speter * \param Unit the translation unit to query. 73518334Speter * \param Index the zero-based diagnostic number to retrieve. 73618334Speter * 73718334Speter * \returns the requested diagnostic. This diagnostic must be freed 73818334Speter * via a call to \c clang_disposeDiagnostic(). 73918334Speter */ 74018334SpeterCINDEX_LINKAGE CXDiagnostic clang_getDiagnostic(CXTranslationUnit Unit, 74118334Speter unsigned Index); 74218334Speter 74318334Speter/** 74418334Speter * \brief Retrieve the complete set of diagnostics associated with a 74518334Speter * translation unit. 74618334Speter * 74718334Speter * \param Unit the translation unit to query. 74818334Speter */ 74918334SpeterCINDEX_LINKAGE CXDiagnosticSet 75018334Speter clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); 75118334Speter 75218334Speter/** 75318334Speter * \brief Destroy a diagnostic. 75418334Speter */ 75518334SpeterCINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); 75650397Sobrien 75718334Speter/** 75818334Speter * \brief Options to control the display of diagnostics. 75918334Speter * 76052284Sobrien * The values in this enum are meant to be combined to customize the 76150397Sobrien * behavior of \c clang_displayDiagnostic(). 76252284Sobrien */ 76350397Sobrienenum CXDiagnosticDisplayOptions { 76450397Sobrien /** 76550397Sobrien * \brief Display the source-location information where the 76650397Sobrien * diagnostic was located. 76750397Sobrien * 76852284Sobrien * When set, diagnostics will be prefixed by the file, line, and 76950397Sobrien * (optionally) column to which the diagnostic refers. For example, 77018334Speter * 77118334Speter * \code 77218334Speter * test.c:28: warning: extra tokens at end of #endif directive 77318334Speter * \endcode 77418334Speter * 77518334Speter * This option corresponds to the clang flag \c -fshow-source-location. 77618334Speter */ 77718334Speter CXDiagnostic_DisplaySourceLocation = 0x01, 77818334Speter 77918334Speter /** 78018334Speter * \brief If displaying the source-location information of the 78118334Speter * diagnostic, also include the column number. 78218334Speter * 78318334Speter * This option corresponds to the clang flag \c -fshow-column. 78418334Speter */ 78518334Speter CXDiagnostic_DisplayColumn = 0x02, 78618334Speter 78718334Speter /** 78818334Speter * \brief If displaying the source-location information of the 78918334Speter * diagnostic, also include information about source ranges in a 79050397Sobrien * machine-parsable format. 79118334Speter * 79218334Speter * This option corresponds to the clang flag 79352284Sobrien * \c -fdiagnostics-print-source-range-info. 79452284Sobrien */ 79518334Speter CXDiagnostic_DisplaySourceRanges = 0x04, 79618334Speter 79750397Sobrien /** 79818334Speter * \brief Display the option name associated with this diagnostic, if any. 79918334Speter * 80018334Speter * The option name displayed (e.g., -Wconversion) will be placed in brackets 80152284Sobrien * after the diagnostic text. This option corresponds to the clang flag 80218334Speter * \c -fdiagnostics-show-option. 80318334Speter */ 80452284Sobrien CXDiagnostic_DisplayOption = 0x08, 80552284Sobrien 80618334Speter /** 80718334Speter * \brief Display the category number associated with this diagnostic, if any. 80818334Speter * 80918334Speter * The category number is displayed within brackets after the diagnostic text. 81018334Speter * This option corresponds to the clang flag 81118334Speter * \c -fdiagnostics-show-category=id. 81218334Speter */ 81318334Speter CXDiagnostic_DisplayCategoryId = 0x10, 81418334Speter 81518334Speter /** 81618334Speter * \brief Display the category name associated with this diagnostic, if any. 81718334Speter * 81818334Speter * The category name is displayed within brackets after the diagnostic text. 81918334Speter * This option corresponds to the clang flag 82018334Speter * \c -fdiagnostics-show-category=name. 82118334Speter */ 82218334Speter CXDiagnostic_DisplayCategoryName = 0x20 82318334Speter}; 82418334Speter 82518334Speter/** 82618334Speter * \brief Format the given diagnostic in a manner that is suitable for display. 82718334Speter * 82818334Speter * This routine will format the given diagnostic to a string, rendering 82950397Sobrien * the diagnostic according to the various options given. The 83018334Speter * \c clang_defaultDiagnosticDisplayOptions() function returns the set of 83152284Sobrien * options that most closely mimics the behavior of the clang compiler. 83252284Sobrien * 83318334Speter * \param Diagnostic The diagnostic to print. 83418334Speter * 83518334Speter * \param Options A set of options that control the diagnostic display, 83618334Speter * created by combining \c CXDiagnosticDisplayOptions values. 83752284Sobrien * 83818334Speter * \returns A new string containing for formatted diagnostic. 83918334Speter */ 84018334SpeterCINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, 84118334Speter unsigned Options); 84218334Speter 84318334Speter/** 84418334Speter * \brief Retrieve the set of display options most similar to the 84518334Speter * default behavior of the clang compiler. 84618334Speter * 84718334Speter * \returns A set of display options suitable for use with \c 84850397Sobrien * clang_displayDiagnostic(). 84952284Sobrien */ 85018334SpeterCINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); 85118334Speter 85218334Speter/** 85318334Speter * \brief Determine the severity of the given diagnostic. 85418334Speter */ 85518334SpeterCINDEX_LINKAGE enum CXDiagnosticSeverity 85652284Sobrienclang_getDiagnosticSeverity(CXDiagnostic); 85718334Speter 85818334Speter/** 85950397Sobrien * \brief Retrieve the source location of the given diagnostic. 86050397Sobrien * 86150397Sobrien * This location is where Clang would print the caret ('^') when 86250397Sobrien * displaying the diagnostic on the command line. 86350397Sobrien */ 86450397SobrienCINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); 86518334Speter 86618334Speter/** 86718334Speter * \brief Retrieve the text of the given diagnostic. 86818334Speter */ 86918334SpeterCINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); 87018334Speter 87150397Sobrien/** 87250397Sobrien * \brief Retrieve the name of the command-line option that enabled this 87318334Speter * diagnostic. 87418334Speter * 87518334Speter * \param Diag The diagnostic to be queried. 87618334Speter * 87718334Speter * \param Disable If non-NULL, will be set to the option that disables this 87852284Sobrien * diagnostic (if any). 87918334Speter * 88052284Sobrien * \returns A string that contains the command-line option used to enable this 88152284Sobrien * warning, such as "-Wconversion" or "-pedantic". 88250397Sobrien */ 88352284SobrienCINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, 88450397Sobrien CXString *Disable); 88550397Sobrien 88650397Sobrien/** 88750397Sobrien * \brief Retrieve the category number for this diagnostic. 88818334Speter * 88918334Speter * Diagnostics can be categorized into groups along with other, related 89018334Speter * diagnostics (e.g., diagnostics under the same warning flag). This routine 89118334Speter * retrieves the category number for the given diagnostic. 89218334Speter * 89352284Sobrien * \returns The number of the category that contains this diagnostic, or zero 89452284Sobrien * if this diagnostic is uncategorized. 89552284Sobrien */ 89652284SobrienCINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); 89718334Speter 89852284Sobrien/** 89918334Speter * \brief Retrieve the name of a particular diagnostic category. This 90018334Speter * is now deprecated. Use clang_getDiagnosticCategoryText() 90118334Speter * instead. 90218334Speter * 90318334Speter * \param Category A diagnostic category number, as returned by 90418334Speter * \c clang_getDiagnosticCategory(). 90518334Speter * 90650397Sobrien * \returns The name of the given diagnostic category. 90718334Speter */ 90818334SpeterCINDEX_DEPRECATED CINDEX_LINKAGE 90918334SpeterCXString clang_getDiagnosticCategoryName(unsigned Category); 91018334Speter 91118334Speter/** 91218334Speter * \brief Retrieve the diagnostic category text for a given diagnostic. 91318334Speter * 91418334Speter * \returns The text of the given diagnostic category. 91518334Speter */ 91618334SpeterCINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); 91718334Speter 91850397Sobrien/** 91918334Speter * \brief Determine the number of source ranges associated with the given 92018334Speter * diagnostic. 92118334Speter */ 92218334SpeterCINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); 92318334Speter 92418334Speter/** 92518334Speter * \brief Retrieve a source range associated with the diagnostic. 92618334Speter * 92718334Speter * A diagnostic's source ranges highlight important elements in the source 92818334Speter * code. On the command line, Clang displays source ranges by 92918334Speter * underlining them with '~' characters. 93018334Speter * 93118334Speter * \param Diagnostic the diagnostic whose range is being extracted. 93218334Speter * 93318334Speter * \param Range the zero-based index specifying which range to 93418334Speter * 93518334Speter * \returns the requested source range. 93650397Sobrien */ 93750397SobrienCINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, 93818334Speter unsigned Range); 93918334Speter 94018334Speter/** 94118334Speter * \brief Determine the number of fix-it hints associated with the 94218334Speter * given diagnostic. 94318334Speter */ 94418334SpeterCINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); 94518334Speter 94618334Speter/** 94718334Speter * \brief Retrieve the replacement information for a given fix-it. 94818334Speter * 94918334Speter * Fix-its are described in terms of a source range whose contents 95018334Speter * should be replaced by a string. This approach generalizes over 95118334Speter * three kinds of operations: removal of source code (the range covers 95218334Speter * the code to be removed and the replacement string is empty), 95318334Speter * replacement of source code (the range covers the code to be 95418334Speter * replaced and the replacement string provides the new code), and 95518334Speter * insertion (both the start and end of the range point at the 95618334Speter * insertion location, and the replacement string provides the text to 95718334Speter * insert). 95850397Sobrien * 95918334Speter * \param Diagnostic The diagnostic whose fix-its are being queried. 96052284Sobrien * 96152284Sobrien * \param FixIt The zero-based index of the fix-it. 96218334Speter * 96318334Speter * \param ReplacementRange The source range whose contents will be 96418334Speter * replaced with the returned replacement string. Note that source 96552284Sobrien * ranges are half-open ranges [a, b), so the source code should be 96618334Speter * replaced from a and up to (but not including) b. 96718334Speter * 96852284Sobrien * \returns A string containing text that should be replace the source 96918334Speter * code indicated by the \c ReplacementRange. 97018334Speter */ 97118334SpeterCINDEX_LINKAGE CXString clang_getDiagnosticFixIt(CXDiagnostic Diagnostic, 97252284Sobrien unsigned FixIt, 97318334Speter CXSourceRange *ReplacementRange); 97418334Speter 97518334Speter/** 97652284Sobrien * @} 97718334Speter */ 97852284Sobrien 97918334Speter/** 98018334Speter * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation 98118334Speter * 98218334Speter * The routines in this group provide the ability to create and destroy 98318334Speter * translation units from files, either by parsing the contents of the files or 98418334Speter * by reading in a serialized representation of a translation unit. 98518334Speter * 98618334Speter * @{ 98718334Speter */ 98818334Speter 98918334Speter/** 99018334Speter * \brief Get the original translation unit source file name. 99150397Sobrien */ 99218334SpeterCINDEX_LINKAGE CXString 99318334Speterclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 99418334Speter 99518334Speter/** 99618334Speter * \brief Return the CXTranslationUnit for a given source file and the provided 99718334Speter * command line arguments one would pass to the compiler. 99818334Speter * 99918334Speter * Note: The 'source_filename' argument is optional. If the caller provides a 100018334Speter * NULL pointer, the name of the source file is expected to reside in the 100118334Speter * specified command line arguments. 100218334Speter * 100318334Speter * Note: When encountered in 'clang_command_line_args', the following options 100418334Speter * are ignored: 100518334Speter * 100618334Speter * '-c' 100718334Speter * '-emit-ast' 100818334Speter * '-fsyntax-only' 100918334Speter * '-o \<output file>' (both '-o' and '\<output file>' are ignored) 101018334Speter * 101118334Speter * \param CIdx The index object with which the translation unit will be 101218334Speter * associated. 101318334Speter * 101418334Speter * \param source_filename The name of the source file to load, or NULL if the 101518334Speter * source file is included in \p clang_command_line_args. 101618334Speter * 101750397Sobrien * \param num_clang_command_line_args The number of command-line arguments in 101818334Speter * \p clang_command_line_args. 101918334Speter * 102018334Speter * \param clang_command_line_args The command-line arguments that would be 102118334Speter * passed to the \c clang executable if it were being invoked out-of-process. 102252284Sobrien * These command-line options will be parsed and will affect how the translation 102318334Speter * unit is parsed. Note that the following options are ignored: '-c', 102418334Speter * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. 102518334Speter * 102618334Speter * \param num_unsaved_files the number of unsaved file entries in \p 102718334Speter * unsaved_files. 102818334Speter * 102918334Speter * \param unsaved_files the files that have not yet been saved to disk 103018334Speter * but may be required for code completion, including the contents of 103118334Speter * those files. The contents and name of these files (as specified by 103218334Speter * CXUnsavedFile) are copied when necessary, so the client only needs to 103318334Speter * guarantee their validity until the call to this function returns. 103418334Speter */ 103518334SpeterCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 103618334Speter CXIndex CIdx, 103718334Speter const char *source_filename, 103818334Speter int num_clang_command_line_args, 103918334Speter const char * const *clang_command_line_args, 104018334Speter unsigned num_unsaved_files, 104118334Speter struct CXUnsavedFile *unsaved_files); 104218334Speter 104318334Speter/** 104418334Speter * \brief Create a translation unit from an AST file (-emit-ast). 104518334Speter */ 104650397SobrienCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit(CXIndex, 104750397Sobrien const char *ast_filename); 104850397Sobrien 104918334Speter/** 105050397Sobrien * \brief Flags that control the creation of translation units. 105150397Sobrien * 105250397Sobrien * The enumerators in this enumeration type are meant to be bitwise 105318334Speter * ORed together to specify which options should be used when 105418334Speter * constructing the translation unit. 105518334Speter */ 105618334Speterenum CXTranslationUnit_Flags { 105718334Speter /** 105818334Speter * \brief Used to indicate that no special translation-unit options are 105918334Speter * needed. 106018334Speter */ 106150397Sobrien CXTranslationUnit_None = 0x0, 106218334Speter 106318334Speter /** 106418334Speter * \brief Used to indicate that the parser should construct a "detailed" 106518334Speter * preprocessing record, including all macro definitions and instantiations. 106618334Speter * 106718334Speter * Constructing a detailed preprocessing record requires more memory 106818334Speter * and time to parse, since the information contained in the record 106918334Speter * is usually not retained. However, it can be useful for 107018334Speter * applications that require more detailed information about the 107118334Speter * behavior of the preprocessor. 107250397Sobrien */ 107318334Speter CXTranslationUnit_DetailedPreprocessingRecord = 0x01, 107450397Sobrien 107550397Sobrien /** 107618334Speter * \brief Used to indicate that the translation unit is incomplete. 107718334Speter * 107818334Speter * When a translation unit is considered "incomplete", semantic 107918334Speter * analysis that is typically performed at the end of the 108018334Speter * translation unit will be suppressed. For example, this suppresses 108150397Sobrien * the completion of tentative declarations in C and of 108218334Speter * instantiation of implicitly-instantiation function templates in 108318334Speter * C++. This option is typically used when parsing a header with the 108418334Speter * intent of producing a precompiled header. 108518334Speter */ 108618334Speter CXTranslationUnit_Incomplete = 0x02, 108718334Speter 108818334Speter /** 108918334Speter * \brief Used to indicate that the translation unit should be built with an 109018334Speter * implicit precompiled header for the preamble. 109118334Speter * 109218334Speter * An implicit precompiled header is used as an optimization when a 109318334Speter * particular translation unit is likely to be reparsed many times 109418334Speter * when the sources aren't changing that often. In this case, an 109518334Speter * implicit precompiled header will be built containing all of the 109618334Speter * initial includes at the top of the main file (what we refer to as 109750397Sobrien * the "preamble" of the file). In subsequent parses, if the 109818334Speter * preamble or the files in it have not changed, \c 109918334Speter * clang_reparseTranslationUnit() will re-use the implicit 110018334Speter * precompiled header to improve parsing performance. 110118334Speter */ 110218334Speter CXTranslationUnit_PrecompiledPreamble = 0x04, 110318334Speter 110418334Speter /** 110518334Speter * \brief Used to indicate that the translation unit should cache some 110618334Speter * code-completion results with each reparse of the source file. 110718334Speter * 110818334Speter * Caching of code-completion results is a performance optimization that 110918334Speter * introduces some overhead to reparsing but improves the performance of 111050397Sobrien * code-completion operations. 111118334Speter */ 111218334Speter CXTranslationUnit_CacheCompletionResults = 0x08, 111318334Speter 111418334Speter /** 111518334Speter * \brief Used to indicate that the translation unit will be serialized with 111618334Speter * \c clang_saveTranslationUnit. 111718334Speter * 111818334Speter * This option is typically used when parsing a header with the intent of 111918334Speter * producing a precompiled header. 112018334Speter */ 112118334Speter CXTranslationUnit_ForSerialization = 0x10, 112218334Speter 112318334Speter /** 112418334Speter * \brief DEPRECATED: Enabled chained precompiled preambles in C++. 112518334Speter * 112618334Speter * Note: this is a *temporary* option that is available only while 112718334Speter * we are testing C++ precompiled preamble support. It is deprecated. 112818334Speter */ 112918334Speter CXTranslationUnit_CXXChainedPCH = 0x20, 113018334Speter 113118334Speter /** 113218334Speter * \brief Used to indicate that function/method bodies should be skipped while 113318334Speter * parsing. 113418334Speter * 113518334Speter * This option can be used to search for declarations/definitions while 113618334Speter * ignoring the usages. 113718334Speter */ 113818334Speter CXTranslationUnit_SkipFunctionBodies = 0x40, 113918334Speter 114018334Speter /** 114150397Sobrien * \brief Used to indicate that brief documentation comments should be 114250397Sobrien * included into the set of code completions returned from this translation 114318334Speter * unit. 114418334Speter */ 114518334Speter CXTranslationUnit_IncludeBriefCommentsInCodeCompletion = 0x80 114618334Speter}; 114718334Speter 114818334Speter/** 114918334Speter * \brief Returns the set of flags that is suitable for parsing a translation 115018334Speter * unit that is being edited. 115118334Speter * 115218334Speter * The set of flags returned provide options for \c clang_parseTranslationUnit() 115318334Speter * to indicate that the translation unit is likely to be reparsed many times, 115418334Speter * either explicitly (via \c clang_reparseTranslationUnit()) or implicitly 115518334Speter * (e.g., by code completion (\c clang_codeCompletionAt())). The returned flag 115618334Speter * set contains an unspecified set of optimizations (e.g., the precompiled 115718334Speter * preamble) geared toward improving the performance of these routines. The 115818334Speter * set of optimizations enabled may change from one version to the next. 115918334Speter */ 116018334SpeterCINDEX_LINKAGE unsigned clang_defaultEditingTranslationUnitOptions(void); 116118334Speter 116218334Speter/** 116318334Speter * \brief Parse the given source file and the translation unit corresponding 116450397Sobrien * to that file. 116518334Speter * 116618334Speter * This routine is the main entry point for the Clang C API, providing the 116718334Speter * ability to parse a source file into a translation unit that can then be 116850397Sobrien * queried by other functions in the API. This routine accepts a set of 116950397Sobrien * command-line arguments so that the compilation can be configured in the same 117018334Speter * way that the compiler is configured on the command line. 117118334Speter * 117218334Speter * \param CIdx The index object with which the translation unit will be 117350397Sobrien * associated. 117450397Sobrien * 117518334Speter * \param source_filename The name of the source file to load, or NULL if the 117618334Speter * source file is included in \p command_line_args. 117718334Speter * 117818334Speter * \param command_line_args The command-line arguments that would be 117918334Speter * passed to the \c clang executable if it were being invoked out-of-process. 118018334Speter * These command-line options will be parsed and will affect how the translation 118118334Speter * unit is parsed. Note that the following options are ignored: '-c', 118218334Speter * '-emit-ast', '-fsyntax-only' (which is the default), and '-o \<output file>'. 118318334Speter * 118418334Speter * \param num_command_line_args The number of command-line arguments in 118518334Speter * \p command_line_args. 118618334Speter * 118718334Speter * \param unsaved_files the files that have not yet been saved to disk 118818334Speter * but may be required for parsing, including the contents of 118918334Speter * those files. The contents and name of these files (as specified by 119018334Speter * CXUnsavedFile) are copied when necessary, so the client only needs to 119118334Speter * guarantee their validity until the call to this function returns. 119218334Speter * 119318334Speter * \param num_unsaved_files the number of unsaved file entries in \p 119418334Speter * unsaved_files. 119518334Speter * 119618334Speter * \param options A bitmask of options that affects how the translation unit 119718334Speter * is managed but not its compilation. This should be a bitwise OR of the 119818334Speter * CXTranslationUnit_XXX flags. 119918334Speter * 120018334Speter * \returns A new translation unit describing the parsed code and containing 120118334Speter * any diagnostics produced by the compiler. If there is a failure from which 120218334Speter * the compiler cannot recover, returns NULL. 120318334Speter */ 120418334SpeterCINDEX_LINKAGE CXTranslationUnit clang_parseTranslationUnit(CXIndex CIdx, 120518334Speter const char *source_filename, 120618334Speter const char * const *command_line_args, 120718334Speter int num_command_line_args, 120818334Speter struct CXUnsavedFile *unsaved_files, 120918334Speter unsigned num_unsaved_files, 121018334Speter unsigned options); 121118334Speter 121218334Speter/** 121318334Speter * \brief Flags that control how translation units are saved. 121418334Speter * 121518334Speter * The enumerators in this enumeration type are meant to be bitwise 121618334Speter * ORed together to specify which options should be used when 121718334Speter * saving the translation unit. 121818334Speter */ 121918334Speterenum CXSaveTranslationUnit_Flags { 122018334Speter /** 122118334Speter * \brief Used to indicate that no special saving options are needed. 122218334Speter */ 122318334Speter CXSaveTranslationUnit_None = 0x0 122418334Speter}; 122518334Speter 122618334Speter/** 122718334Speter * \brief Returns the set of flags that is suitable for saving a translation 122818334Speter * unit. 122918334Speter * 123018334Speter * The set of flags returned provide options for 123118334Speter * \c clang_saveTranslationUnit() by default. The returned flag 123218334Speter * set contains an unspecified set of options that save translation units with 123318334Speter * the most commonly-requested data. 123450397Sobrien */ 123518334SpeterCINDEX_LINKAGE unsigned clang_defaultSaveOptions(CXTranslationUnit TU); 123618334Speter 123718334Speter/** 123818334Speter * \brief Describes the kind of error that occurred (if any) in a call to 123918334Speter * \c clang_saveTranslationUnit(). 124018334Speter */ 124118334Speterenum CXSaveError { 124218334Speter /** 124318334Speter * \brief Indicates that no error occurred while saving a translation unit. 124418334Speter */ 124518334Speter CXSaveError_None = 0, 124618334Speter 124750397Sobrien /** 124818334Speter * \brief Indicates that an unknown error occurred while attempting to save 124950397Sobrien * the file. 125018334Speter * 125118334Speter * This error typically indicates that file I/O failed when attempting to 125218334Speter * write the file. 125352284Sobrien */ 125418334Speter CXSaveError_Unknown = 1, 125518334Speter 125618334Speter /** 125750397Sobrien * \brief Indicates that errors during translation prevented this attempt 125818334Speter * to save the translation unit. 125918334Speter * 126052284Sobrien * Errors that prevent the translation unit from being saved can be 126118334Speter * extracted using \c clang_getNumDiagnostics() and \c clang_getDiagnostic(). 126218334Speter */ 126318334Speter CXSaveError_TranslationErrors = 2, 126418334Speter 126518334Speter /** 126618334Speter * \brief Indicates that the translation unit to be saved was somehow 126718334Speter * invalid (e.g., NULL). 126818334Speter */ 126918334Speter CXSaveError_InvalidTU = 3 127018334Speter}; 127118334Speter 127218334Speter/** 127318334Speter * \brief Saves a translation unit into a serialized representation of 127418334Speter * that translation unit on disk. 127518334Speter * 127618334Speter * Any translation unit that was parsed without error can be saved 127718334Speter * into a file. The translation unit can then be deserialized into a 127818334Speter * new \c CXTranslationUnit with \c clang_createTranslationUnit() or, 127918334Speter * if it is an incomplete translation unit that corresponds to a 128018334Speter * header, used as a precompiled header when parsing other translation 128118334Speter * units. 128218334Speter * 128318334Speter * \param TU The translation unit to save. 128450397Sobrien * 128518334Speter * \param FileName The file to which the translation unit will be saved. 128652284Sobrien * 128718334Speter * \param options A bitmask of options that affects how the translation unit 128818334Speter * is saved. This should be a bitwise OR of the 128918334Speter * CXSaveTranslationUnit_XXX flags. 129018334Speter * 129118334Speter * \returns A value that will match one of the enumerators of the CXSaveError 129250397Sobrien * enumeration. Zero (CXSaveError_None) indicates that the translation unit was 129318334Speter * saved successfully, while a non-zero value indicates that a problem occurred. 129418334Speter */ 129518334SpeterCINDEX_LINKAGE int clang_saveTranslationUnit(CXTranslationUnit TU, 129618334Speter const char *FileName, 129718334Speter unsigned options); 129850397Sobrien 129918334Speter/** 130018334Speter * \brief Destroy the specified CXTranslationUnit object. 130118334Speter */ 130218334SpeterCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 130318334Speter 130418334Speter/** 130518334Speter * \brief Flags that control the reparsing of translation units. 130618334Speter * 130718334Speter * The enumerators in this enumeration type are meant to be bitwise 130818334Speter * ORed together to specify which options should be used when 130918334Speter * reparsing the translation unit. 131018334Speter */ 131118334Speterenum CXReparse_Flags { 131218334Speter /** 131318334Speter * \brief Used to indicate that no special reparsing options are needed. 131418334Speter */ 131518334Speter CXReparse_None = 0x0 131618334Speter}; 131718334Speter 131818334Speter/** 131950397Sobrien * \brief Returns the set of flags that is suitable for reparsing a translation 132018334Speter * unit. 132118334Speter * 132218334Speter * The set of flags returned provide options for 132318334Speter * \c clang_reparseTranslationUnit() by default. The returned flag 132418334Speter * set contains an unspecified set of optimizations geared toward common uses 132518334Speter * of reparsing. The set of optimizations enabled may change from one version 132618334Speter * to the next. 132718334Speter */ 132818334SpeterCINDEX_LINKAGE unsigned clang_defaultReparseOptions(CXTranslationUnit TU); 132918334Speter 133050397Sobrien/** 133118334Speter * \brief Reparse the source files that produced this translation unit. 133218334Speter * 133318334Speter * This routine can be used to re-parse the source files that originally 133418334Speter * created the given translation unit, for example because those source files 133518334Speter * have changed (either on disk or as passed via \p unsaved_files). The 133618334Speter * source code will be reparsed with the same command-line options as it 133718334Speter * was originally parsed. 133818334Speter * 133918334Speter * Reparsing a translation unit invalidates all cursors and source locations 134018334Speter * that refer into that translation unit. This makes reparsing a translation 134118334Speter * unit semantically equivalent to destroying the translation unit and then 134218334Speter * creating a new translation unit with the same command-line arguments. 134318334Speter * However, it may be more efficient to reparse a translation 134418334Speter * unit using this routine. 134518334Speter * 134618334Speter * \param TU The translation unit whose contents will be re-parsed. The 134718334Speter * translation unit must originally have been built with 134818334Speter * \c clang_createTranslationUnitFromSourceFile(). 134918334Speter * 135050397Sobrien * \param num_unsaved_files The number of unsaved file entries in \p 135118334Speter * unsaved_files. 135218334Speter * 135318334Speter * \param unsaved_files The files that have not yet been saved to disk 135418334Speter * but may be required for parsing, including the contents of 135518334Speter * those files. The contents and name of these files (as specified by 135618334Speter * CXUnsavedFile) are copied when necessary, so the client only needs to 135718334Speter * guarantee their validity until the call to this function returns. 135818334Speter * 135918334Speter * \param options A bitset of options composed of the flags in CXReparse_Flags. 136018334Speter * The function \c clang_defaultReparseOptions() produces a default set of 136150397Sobrien * options recommended for most uses, based on the translation unit. 136218334Speter * 136318334Speter * \returns 0 if the sources could be reparsed. A non-zero value will be 136418334Speter * returned if reparsing was impossible, such that the translation unit is 136518334Speter * invalid. In such cases, the only valid call for \p TU is 136618334Speter * \c clang_disposeTranslationUnit(TU). 136718334Speter */ 136818334SpeterCINDEX_LINKAGE int clang_reparseTranslationUnit(CXTranslationUnit TU, 136950397Sobrien unsigned num_unsaved_files, 137050397Sobrien struct CXUnsavedFile *unsaved_files, 137118334Speter unsigned options); 137218334Speter 137318334Speter/** 137418334Speter * \brief Categorizes how memory is being used by a translation unit. 137518334Speter */ 137618334Speterenum CXTUResourceUsageKind { 137718334Speter CXTUResourceUsage_AST = 1, 137818334Speter CXTUResourceUsage_Identifiers = 2, 137918334Speter CXTUResourceUsage_Selectors = 3, 138018334Speter CXTUResourceUsage_GlobalCompletionResults = 4, 138118334Speter CXTUResourceUsage_SourceManagerContentCache = 5, 138218334Speter CXTUResourceUsage_AST_SideTables = 6, 138350397Sobrien CXTUResourceUsage_SourceManager_Membuffer_Malloc = 7, 138418334Speter CXTUResourceUsage_SourceManager_Membuffer_MMap = 8, 138518334Speter CXTUResourceUsage_ExternalASTSource_Membuffer_Malloc = 9, 138618334Speter CXTUResourceUsage_ExternalASTSource_Membuffer_MMap = 10, 138718334Speter CXTUResourceUsage_Preprocessor = 11, 138818334Speter CXTUResourceUsage_PreprocessingRecord = 12, 138918334Speter CXTUResourceUsage_SourceManager_DataStructures = 13, 139018334Speter CXTUResourceUsage_Preprocessor_HeaderSearch = 14, 139118334Speter CXTUResourceUsage_MEMORY_IN_BYTES_BEGIN = CXTUResourceUsage_AST, 139218334Speter CXTUResourceUsage_MEMORY_IN_BYTES_END = 139318334Speter CXTUResourceUsage_Preprocessor_HeaderSearch, 139418334Speter 139518334Speter CXTUResourceUsage_First = CXTUResourceUsage_AST, 139618334Speter CXTUResourceUsage_Last = CXTUResourceUsage_Preprocessor_HeaderSearch 139718334Speter}; 139818334Speter 139918334Speter/** 140018334Speter * \brief Returns the human-readable null-terminated C string that represents 140118334Speter * the name of the memory category. This string should never be freed. 140218334Speter */ 140318334SpeterCINDEX_LINKAGE 140418334Speterconst char *clang_getTUResourceUsageName(enum CXTUResourceUsageKind kind); 140550397Sobrien 140618334Spetertypedef struct CXTUResourceUsageEntry { 140718334Speter /* \brief The memory usage category. */ 140818334Speter enum CXTUResourceUsageKind kind; 140918334Speter /* \brief Amount of resources used. 141018334Speter The units will depend on the resource kind. */ 141118334Speter unsigned long amount; 141218334Speter} CXTUResourceUsageEntry; 141318334Speter 141418334Speter/** 141518334Speter * \brief The memory usage of a CXTranslationUnit, broken into categories. 141618334Speter */ 141718334Spetertypedef struct CXTUResourceUsage { 141818334Speter /* \brief Private data member, used for queries. */ 141918334Speter void *data; 142018334Speter 142118334Speter /* \brief The number of entries in the 'entries' array. */ 142218334Speter unsigned numEntries; 142318334Speter 142418334Speter /* \brief An array of key-value pairs, representing the breakdown of memory 142518334Speter usage. */ 142618334Speter CXTUResourceUsageEntry *entries; 142718334Speter 142818334Speter} CXTUResourceUsage; 142918334Speter 143018334Speter/** 143150397Sobrien * \brief Return the memory usage of a translation unit. This object 143218334Speter * should be released with clang_disposeCXTUResourceUsage(). 143318334Speter */ 143418334SpeterCINDEX_LINKAGE CXTUResourceUsage clang_getCXTUResourceUsage(CXTranslationUnit TU); 143518334Speter 143618334SpeterCINDEX_LINKAGE void clang_disposeCXTUResourceUsage(CXTUResourceUsage usage); 143718334Speter 143818334Speter/** 143918334Speter * @} 144018334Speter */ 144118334Speter 144218334Speter/** 144318334Speter * \brief Describes the kind of entity that a cursor refers to. 144418334Speter */ 144518334Speterenum CXCursorKind { 144618334Speter /* Declarations */ 144718334Speter /** 144818334Speter * \brief A declaration whose specific kind is not exposed via this 144918334Speter * interface. 145018334Speter * 145118334Speter * Unexposed declarations have the same operations as any other kind 145250397Sobrien * of declaration; one can extract their location information, 145318334Speter * spelling, find their definitions, etc. However, the specific kind 145418334Speter * of the declaration is not reported. 145518334Speter */ 145618334Speter CXCursor_UnexposedDecl = 1, 145718334Speter /** \brief A C or C++ struct. */ 145852284Sobrien CXCursor_StructDecl = 2, 145952284Sobrien /** \brief A C or C++ union. */ 146052284Sobrien CXCursor_UnionDecl = 3, 146152284Sobrien /** \brief A C++ class. */ 146252284Sobrien CXCursor_ClassDecl = 4, 146352284Sobrien /** \brief An enumeration. */ 146452284Sobrien CXCursor_EnumDecl = 5, 146552284Sobrien /** 146618334Speter * \brief A field (in C) or non-static data member (in C++) in a 146718334Speter * struct, union, or C++ class. 146818334Speter */ 146918334Speter CXCursor_FieldDecl = 6, 147018334Speter /** \brief An enumerator constant. */ 147118334Speter CXCursor_EnumConstantDecl = 7, 147218334Speter /** \brief A function. */ 147352284Sobrien CXCursor_FunctionDecl = 8, 147452284Sobrien /** \brief A variable. */ 147552284Sobrien CXCursor_VarDecl = 9, 147652284Sobrien /** \brief A function or method parameter. */ 147752284Sobrien CXCursor_ParmDecl = 10, 147852284Sobrien /** \brief An Objective-C \@interface. */ 147950397Sobrien CXCursor_ObjCInterfaceDecl = 11, 148018334Speter /** \brief An Objective-C \@interface for a category. */ 148118334Speter CXCursor_ObjCCategoryDecl = 12, 148218334Speter /** \brief An Objective-C \@protocol declaration. */ 148318334Speter CXCursor_ObjCProtocolDecl = 13, 148418334Speter /** \brief An Objective-C \@property declaration. */ 148518334Speter CXCursor_ObjCPropertyDecl = 14, 148618334Speter /** \brief An Objective-C instance variable. */ 148718334Speter CXCursor_ObjCIvarDecl = 15, 148818334Speter /** \brief An Objective-C instance method. */ 148918334Speter CXCursor_ObjCInstanceMethodDecl = 16, 149018334Speter /** \brief An Objective-C class method. */ 149118334Speter CXCursor_ObjCClassMethodDecl = 17, 149218334Speter /** \brief An Objective-C \@implementation. */ 149318334Speter CXCursor_ObjCImplementationDecl = 18, 149418334Speter /** \brief An Objective-C \@implementation for a category. */ 149518334Speter CXCursor_ObjCCategoryImplDecl = 19, 149652284Sobrien /** \brief A typedef */ 149752284Sobrien CXCursor_TypedefDecl = 20, 149852284Sobrien /** \brief A C++ class method. */ 149952284Sobrien CXCursor_CXXMethod = 21, 150018334Speter /** \brief A C++ namespace. */ 150152284Sobrien CXCursor_Namespace = 22, 150218334Speter /** \brief A linkage specification, e.g. 'extern "C"'. */ 150352284Sobrien CXCursor_LinkageSpec = 23, 150452284Sobrien /** \brief A C++ constructor. */ 150552284Sobrien CXCursor_Constructor = 24, 150652284Sobrien /** \brief A C++ destructor. */ 150752284Sobrien CXCursor_Destructor = 25, 150818334Speter /** \brief A C++ conversion function. */ 150918334Speter CXCursor_ConversionFunction = 26, 151018334Speter /** \brief A C++ template type parameter. */ 151118334Speter CXCursor_TemplateTypeParameter = 27, 151218334Speter /** \brief A C++ non-type template parameter. */ 151318334Speter CXCursor_NonTypeTemplateParameter = 28, 151418334Speter /** \brief A C++ template template parameter. */ 151518334Speter CXCursor_TemplateTemplateParameter = 29, 151618334Speter /** \brief A C++ function template. */ 151718334Speter CXCursor_FunctionTemplate = 30, 151818334Speter /** \brief A C++ class template. */ 151918334Speter CXCursor_ClassTemplate = 31, 152018334Speter /** \brief A C++ class template partial specialization. */ 152118334Speter CXCursor_ClassTemplatePartialSpecialization = 32, 152218334Speter /** \brief A C++ namespace alias declaration. */ 152350397Sobrien CXCursor_NamespaceAlias = 33, 152418334Speter /** \brief A C++ using directive. */ 152518334Speter CXCursor_UsingDirective = 34, 152618334Speter /** \brief A C++ using declaration. */ 152718334Speter CXCursor_UsingDeclaration = 35, 152818334Speter /** \brief A C++ alias declaration */ 152918334Speter CXCursor_TypeAliasDecl = 36, 153018334Speter /** \brief An Objective-C \@synthesize definition. */ 153118334Speter CXCursor_ObjCSynthesizeDecl = 37, 153218334Speter /** \brief An Objective-C \@dynamic definition. */ 153318334Speter CXCursor_ObjCDynamicDecl = 38, 153418334Speter /** \brief An access specifier. */ 153518334Speter CXCursor_CXXAccessSpecifier = 39, 153618334Speter 153718334Speter CXCursor_FirstDecl = CXCursor_UnexposedDecl, 153818334Speter CXCursor_LastDecl = CXCursor_CXXAccessSpecifier, 153918334Speter 154018334Speter /* References */ 154118334Speter CXCursor_FirstRef = 40, /* Decl references */ 154218334Speter CXCursor_ObjCSuperClassRef = 40, 154318334Speter CXCursor_ObjCProtocolRef = 41, 154418334Speter CXCursor_ObjCClassRef = 42, 154518334Speter /** 154618334Speter * \brief A reference to a type declaration. 154718334Speter * 154818334Speter * A type reference occurs anywhere where a type is named but not 154918334Speter * declared. For example, given: 155018334Speter * 155118334Speter * \code 155218334Speter * typedef unsigned size_type; 155318334Speter * size_type size; 155452284Sobrien * \endcode 155518334Speter * 155618334Speter * The typedef is a declaration of size_type (CXCursor_TypedefDecl), 155718334Speter * while the type of the variable "size" is referenced. The cursor 155818334Speter * referenced by the type of size is the typedef for size_type. 155918334Speter */ 156018334Speter CXCursor_TypeRef = 43, 156118334Speter CXCursor_CXXBaseSpecifier = 44, 156218334Speter /** 156318334Speter * \brief A reference to a class template, function template, template 156418334Speter * template parameter, or class template partial specialization. 156518334Speter */ 156650397Sobrien CXCursor_TemplateRef = 45, 156718334Speter /** 156818334Speter * \brief A reference to a namespace or namespace alias. 156918334Speter */ 157018334Speter CXCursor_NamespaceRef = 46, 157118334Speter /** 157218334Speter * \brief A reference to a member of a struct, union, or class that occurs in 157318334Speter * some non-expression context, e.g., a designated initializer. 157418334Speter */ 157518334Speter CXCursor_MemberRef = 47, 157618334Speter /** 157718334Speter * \brief A reference to a labeled statement. 157818334Speter * 157918334Speter * This cursor kind is used to describe the jump to "start_over" in the 158018334Speter * goto statement in the following example: 158118334Speter * 158218334Speter * \code 158318334Speter * start_over: 158418334Speter * ++counter; 158518334Speter * 158618334Speter * goto start_over; 158718334Speter * \endcode 158818334Speter * 158918334Speter * A label reference cursor refers to a label statement. 159018334Speter */ 159118334Speter CXCursor_LabelRef = 48, 159218334Speter 159318334Speter /** 159418334Speter * \brief A reference to a set of overloaded functions or function templates 159550397Sobrien * that has not yet been resolved to a specific function or function template. 159618334Speter * 159718334Speter * An overloaded declaration reference cursor occurs in C++ templates where 159818334Speter * a dependent name refers to a function. For example: 159918334Speter * 160018334Speter * \code 160118334Speter * template<typename T> void swap(T&, T&); 160218334Speter * 160318334Speter * struct X { ... }; 160418334Speter * void swap(X&, X&); 160518334Speter * 160618334Speter * template<typename T> 160718334Speter * void reverse(T* first, T* last) { 160818334Speter * while (first < last - 1) { 160918334Speter * swap(*first, *--last); 161018334Speter * ++first; 161118334Speter * } 161218334Speter * } 161350397Sobrien * 161418334Speter * struct Y { }; 161518334Speter * void swap(Y&, Y&); 161618334Speter * \endcode 161718334Speter * 161818334Speter * Here, the identifier "swap" is associated with an overloaded declaration 161918334Speter * reference. In the template definition, "swap" refers to either of the two 162050397Sobrien * "swap" functions declared above, so both results will be available. At 162118334Speter * instantiation time, "swap" may also refer to other functions found via 162218334Speter * argument-dependent lookup (e.g., the "swap" function at the end of the 162318334Speter * example). 162418334Speter * 162518334Speter * The functions \c clang_getNumOverloadedDecls() and 162618334Speter * \c clang_getOverloadedDecl() can be used to retrieve the definitions 162718334Speter * referenced by this cursor. 162850397Sobrien */ 162918334Speter CXCursor_OverloadedDeclRef = 49, 163018334Speter 163118334Speter /** 163218334Speter * \brief A reference to a variable that occurs in some non-expression 163350397Sobrien * context, e.g., a C++ lambda capture list. 163418334Speter */ 163518334Speter CXCursor_VariableRef = 50, 163618334Speter 163718334Speter CXCursor_LastRef = CXCursor_VariableRef, 163818334Speter 163918334Speter /* Error conditions */ 164018334Speter CXCursor_FirstInvalid = 70, 164118334Speter CXCursor_InvalidFile = 70, 164218334Speter CXCursor_NoDeclFound = 71, 164318334Speter CXCursor_NotImplemented = 72, 164418334Speter CXCursor_InvalidCode = 73, 164518334Speter CXCursor_LastInvalid = CXCursor_InvalidCode, 164618334Speter 164718334Speter /* Expressions */ 164818334Speter CXCursor_FirstExpr = 100, 164918334Speter 165018334Speter /** 165118334Speter * \brief An expression whose specific kind is not exposed via this 165218334Speter * interface. 165350397Sobrien * 165418334Speter * Unexposed expressions have the same operations as any other kind 165518334Speter * of expression; one can extract their location information, 165618334Speter * spelling, children, etc. However, the specific kind of the 165718334Speter * expression is not reported. 165850397Sobrien */ 165918334Speter CXCursor_UnexposedExpr = 100, 166018334Speter 166118334Speter /** 166218334Speter * \brief An expression that refers to some value declaration, such 166318334Speter * as a function, varible, or enumerator. 166418334Speter */ 166518334Speter CXCursor_DeclRefExpr = 101, 166618334Speter 166718334Speter /** 166818334Speter * \brief An expression that refers to a member of a struct, union, 166918334Speter * class, Objective-C class, etc. 167018334Speter */ 167118334Speter CXCursor_MemberRefExpr = 102, 167218334Speter 167318334Speter /** \brief An expression that calls a function. */ 167418334Speter CXCursor_CallExpr = 103, 167518334Speter 167618334Speter /** \brief An expression that sends a message to an Objective-C 167718334Speter object or class. */ 167818334Speter CXCursor_ObjCMessageExpr = 104, 167918334Speter 168018334Speter /** \brief An expression that represents a block literal. */ 168118334Speter CXCursor_BlockExpr = 105, 168218334Speter 168350397Sobrien /** \brief An integer literal. 168418334Speter */ 168518334Speter CXCursor_IntegerLiteral = 106, 168618334Speter 168718334Speter /** \brief A floating point number literal. 168818334Speter */ 168918334Speter CXCursor_FloatingLiteral = 107, 169018334Speter 169118334Speter /** \brief An imaginary number literal. 169218334Speter */ 169318334Speter CXCursor_ImaginaryLiteral = 108, 169450397Sobrien 169518334Speter /** \brief A string literal. 169618334Speter */ 169718334Speter CXCursor_StringLiteral = 109, 169818334Speter 169918334Speter /** \brief A character literal. 170018334Speter */ 170118334Speter CXCursor_CharacterLiteral = 110, 170218334Speter 170318334Speter /** \brief A parenthesized expression, e.g. "(1)". 170418334Speter * 170518334Speter * This AST node is only formed if full location information is requested. 170618334Speter */ 170718334Speter CXCursor_ParenExpr = 111, 170850397Sobrien 170950397Sobrien /** \brief This represents the unary-expression's (except sizeof and 171018334Speter * alignof). 171118334Speter */ 171218334Speter CXCursor_UnaryOperator = 112, 171318334Speter 171418334Speter /** \brief [C99 6.5.2.1] Array Subscripting. 171518334Speter */ 171618334Speter CXCursor_ArraySubscriptExpr = 113, 171718334Speter 171818334Speter /** \brief A builtin binary operation expression such as "x + y" or 171918334Speter * "x <= y". 172018334Speter */ 172118334Speter CXCursor_BinaryOperator = 114, 172218334Speter 172318334Speter /** \brief Compound assignment such as "+=". 172418334Speter */ 172518334Speter CXCursor_CompoundAssignOperator = 115, 172618334Speter 172718334Speter /** \brief The ?: ternary operator. 172818334Speter */ 172918334Speter CXCursor_ConditionalOperator = 116, 173018334Speter 173118334Speter /** \brief An explicit cast in C (C99 6.5.4) or a C-style cast in C++ 173218334Speter * (C++ [expr.cast]), which uses the syntax (Type)expr. 173318334Speter * 173418334Speter * For example: (int)f. 173518334Speter */ 173650397Sobrien CXCursor_CStyleCastExpr = 117, 173718334Speter 173818334Speter /** \brief [C99 6.5.2.5] 173918334Speter */ 174018334Speter CXCursor_CompoundLiteralExpr = 118, 174118334Speter 174218334Speter /** \brief Describes an C or C++ initializer list. 174318334Speter */ 174418334Speter CXCursor_InitListExpr = 119, 174518334Speter 174618334Speter /** \brief The GNU address of label extension, representing &&label. 174718334Speter */ 174818334Speter CXCursor_AddrLabelExpr = 120, 174918334Speter 175018334Speter /** \brief This is the GNU Statement Expression extension: ({int X=4; X;}) 175118334Speter */ 175218334Speter CXCursor_StmtExpr = 121, 175318334Speter 175418334Speter /** \brief Represents a C11 generic selection. 175518334Speter */ 175618334Speter CXCursor_GenericSelectionExpr = 122, 175718334Speter 175818334Speter /** \brief Implements the GNU __null extension, which is a name for a null 175918334Speter * pointer constant that has integral type (e.g., int or long) and is the same 176018334Speter * size and alignment as a pointer. 176118334Speter * 176218334Speter * The __null extension is typically only used by system headers, which define 176318334Speter * NULL as __null in C++ rather than using 0 (which is an integer that may not 176418334Speter * match the size of a pointer). 176518334Speter */ 176618334Speter CXCursor_GNUNullExpr = 123, 176752284Sobrien 176818334Speter /** \brief C++'s static_cast<> expression. 176918334Speter */ 177052284Sobrien CXCursor_CXXStaticCastExpr = 124, 177152284Sobrien 177252284Sobrien /** \brief C++'s dynamic_cast<> expression. 177352284Sobrien */ 177452284Sobrien CXCursor_CXXDynamicCastExpr = 125, 177552284Sobrien 177652284Sobrien /** \brief C++'s reinterpret_cast<> expression. 177752284Sobrien */ 177852284Sobrien CXCursor_CXXReinterpretCastExpr = 126, 177918334Speter 178018334Speter /** \brief C++'s const_cast<> expression. 178118334Speter */ 178218334Speter CXCursor_CXXConstCastExpr = 127, 178318334Speter 178418334Speter /** \brief Represents an explicit C++ type conversion that uses "functional" 178518334Speter * notion (C++ [expr.type.conv]). 178618334Speter * 178718334Speter * Example: 178850397Sobrien * \code 178950397Sobrien * x = int(0.5); 179052284Sobrien * \endcode 179118334Speter */ 179218334Speter CXCursor_CXXFunctionalCastExpr = 128, 179318334Speter 179450397Sobrien /** \brief A C++ typeid expression (C++ [expr.typeid]). 179518334Speter */ 179650397Sobrien CXCursor_CXXTypeidExpr = 129, 179750397Sobrien 179850397Sobrien /** \brief [C++ 2.13.5] C++ Boolean Literal. 179950397Sobrien */ 180050397Sobrien CXCursor_CXXBoolLiteralExpr = 130, 180150397Sobrien 180250397Sobrien /** \brief [C++0x 2.14.7] C++ Pointer Literal. 180350397Sobrien */ 180450397Sobrien CXCursor_CXXNullPtrLiteralExpr = 131, 180550397Sobrien 180650397Sobrien /** \brief Represents the "this" expression in C++ 180750397Sobrien */ 180850397Sobrien CXCursor_CXXThisExpr = 132, 180950397Sobrien 181050397Sobrien /** \brief [C++ 15] C++ Throw Expression. 181150397Sobrien * 181250397Sobrien * This handles 'throw' and 'throw' assignment-expression. When 181350397Sobrien * assignment-expression isn't present, Op will be null. 181450397Sobrien */ 181550397Sobrien CXCursor_CXXThrowExpr = 133, 181650397Sobrien 181750397Sobrien /** \brief A new expression for memory allocation and constructor calls, e.g: 181818334Speter * "new CXXNewExpr(foo)". 181950397Sobrien */ 182018334Speter CXCursor_CXXNewExpr = 134, 182118334Speter 182218334Speter /** \brief A delete expression for memory deallocation and destructor calls, 182318334Speter * e.g. "delete[] pArray". 182418334Speter */ 182518334Speter CXCursor_CXXDeleteExpr = 135, 182618334Speter 182718334Speter /** \brief A unary expression. 182818334Speter */ 182918334Speter CXCursor_UnaryExpr = 136, 183018334Speter 183118334Speter /** \brief An Objective-C string literal i.e. @"foo". 183218334Speter */ 183318334Speter CXCursor_ObjCStringLiteral = 137, 183418334Speter 183518334Speter /** \brief An Objective-C \@encode expression. 183618334Speter */ 183718334Speter CXCursor_ObjCEncodeExpr = 138, 183818334Speter 183918334Speter /** \brief An Objective-C \@selector expression. 184018334Speter */ 184118334Speter CXCursor_ObjCSelectorExpr = 139, 184250397Sobrien 184318334Speter /** \brief An Objective-C \@protocol expression. 184418334Speter */ 184518334Speter CXCursor_ObjCProtocolExpr = 140, 184618334Speter 184718334Speter /** \brief An Objective-C "bridged" cast expression, which casts between 184818334Speter * Objective-C pointers and C pointers, transferring ownership in the process. 184918334Speter * 185018334Speter * \code 185150397Sobrien * NSString *str = (__bridge_transfer NSString *)CFCreateString(); 185250397Sobrien * \endcode 185318334Speter */ 185418334Speter CXCursor_ObjCBridgedCastExpr = 141, 185518334Speter 185618334Speter /** \brief Represents a C++0x pack expansion that produces a sequence of 185752284Sobrien * expressions. 185852284Sobrien * 185952284Sobrien * A pack expansion expression contains a pattern (which itself is an 186052284Sobrien * expression) followed by an ellipsis. For example: 186118334Speter * 186218334Speter * \code 186318334Speter * template<typename F, typename ...Types> 186450397Sobrien * void forward(F f, Types &&...args) { 186518334Speter * f(static_cast<Types&&>(args)...); 186618334Speter * } 186718334Speter * \endcode 186818334Speter */ 186918334Speter CXCursor_PackExpansionExpr = 142, 187050397Sobrien 187118334Speter /** \brief Represents an expression that computes the length of a parameter 187218334Speter * pack. 187318334Speter * 187418334Speter * \code 187518334Speter * template<typename ...Types> 187618334Speter * struct count { 187718334Speter * static const unsigned value = sizeof...(Types); 187818334Speter * }; 187950397Sobrien * \endcode 188018334Speter */ 188118334Speter CXCursor_SizeOfPackExpr = 143, 188218334Speter 188318334Speter /* \brief Represents a C++ lambda expression that produces a local function 188450397Sobrien * object. 188518334Speter * 188618334Speter * \code 188718334Speter * void abssort(float *x, unsigned N) { 188818334Speter * std::sort(x, x + N, 188952284Sobrien * [](float a, float b) { 189052284Sobrien * return std::abs(a) < std::abs(b); 189118334Speter * }); 189252284Sobrien * } 189352284Sobrien * \endcode 189418334Speter */ 189518334Speter CXCursor_LambdaExpr = 144, 189618334Speter 189718334Speter /** \brief Objective-c Boolean Literal. 189818334Speter */ 189950397Sobrien CXCursor_ObjCBoolLiteralExpr = 145, 190018334Speter 190118334Speter CXCursor_LastExpr = CXCursor_ObjCBoolLiteralExpr, 190218334Speter 190318334Speter /* Statements */ 190418334Speter CXCursor_FirstStmt = 200, 190518334Speter /** 190618334Speter * \brief A statement whose specific kind is not exposed via this 190718334Speter * interface. 190818334Speter * 190918334Speter * Unexposed statements have the same operations as any other kind of 191018334Speter * statement; one can extract their location information, spelling, 191118334Speter * children, etc. However, the specific kind of the statement is not 191218334Speter * reported. 191318334Speter */ 191418334Speter CXCursor_UnexposedStmt = 200, 191518334Speter 191618334Speter /** \brief A labelled statement in a function. 191750397Sobrien * 191818334Speter * This cursor kind is used to describe the "start_over:" label statement in 191918334Speter * the following example: 192018334Speter * 192118334Speter * \code 192218334Speter * start_over: 192318334Speter * ++counter; 192418334Speter * \endcode 192518334Speter * 192618334Speter */ 192718334Speter CXCursor_LabelStmt = 201, 192818334Speter 192918334Speter /** \brief A group of statements like { stmt stmt }. 193018334Speter * 193118334Speter * This cursor kind is used to describe compound statements, e.g. function 193218334Speter * bodies. 193318334Speter */ 193418334Speter CXCursor_CompoundStmt = 202, 193518334Speter 193618334Speter /** \brief A case statment. 193718334Speter */ 193818334Speter CXCursor_CaseStmt = 203, 193918334Speter 194018334Speter /** \brief A default statement. 194118334Speter */ 194218334Speter CXCursor_DefaultStmt = 204, 194318334Speter 194418334Speter /** \brief An if statement 194518334Speter */ 194650397Sobrien CXCursor_IfStmt = 205, 194718334Speter 194818334Speter /** \brief A switch statement. 194918334Speter */ 195018334Speter CXCursor_SwitchStmt = 206, 195118334Speter 195250397Sobrien /** \brief A while statement. 195318334Speter */ 195418334Speter CXCursor_WhileStmt = 207, 195518334Speter 195618334Speter /** \brief A do statement. 195718334Speter */ 195818334Speter CXCursor_DoStmt = 208, 195918334Speter 196018334Speter /** \brief A for statement. 196118334Speter */ 196218334Speter CXCursor_ForStmt = 209, 196318334Speter 196418334Speter /** \brief A goto statement. 196518334Speter */ 196618334Speter CXCursor_GotoStmt = 210, 196718334Speter 196818334Speter /** \brief An indirect goto statement. 196918334Speter */ 197018334Speter CXCursor_IndirectGotoStmt = 211, 197118334Speter 197218334Speter /** \brief A continue statement. 197318334Speter */ 197418334Speter CXCursor_ContinueStmt = 212, 197518334Speter 197618334Speter /** \brief A break statement. 197718334Speter */ 197818334Speter CXCursor_BreakStmt = 213, 197918334Speter 198018334Speter /** \brief A return statement. 198118334Speter */ 198218334Speter CXCursor_ReturnStmt = 214, 198318334Speter 198418334Speter /** \brief A GCC inline assembly statement extension. 198518334Speter */ 198618334Speter CXCursor_GCCAsmStmt = 215, 198718334Speter CXCursor_AsmStmt = CXCursor_GCCAsmStmt, 198850397Sobrien 198918334Speter /** \brief Objective-C's overall \@try-\@catch-\@finally statement. 199018334Speter */ 199118334Speter CXCursor_ObjCAtTryStmt = 216, 199218334Speter 199318334Speter /** \brief Objective-C's \@catch statement. 199450397Sobrien */ 199518334Speter CXCursor_ObjCAtCatchStmt = 217, 199618334Speter 199718334Speter /** \brief Objective-C's \@finally statement. 199818334Speter */ 199950397Sobrien CXCursor_ObjCAtFinallyStmt = 218, 200018334Speter 200118334Speter /** \brief Objective-C's \@throw statement. 200218334Speter */ 200318334Speter CXCursor_ObjCAtThrowStmt = 219, 200418334Speter 200518334Speter /** \brief Objective-C's \@synchronized statement. 200618334Speter */ 200718334Speter CXCursor_ObjCAtSynchronizedStmt = 220, 200818334Speter 200918334Speter /** \brief Objective-C's autorelease pool statement. 201018334Speter */ 201150397Sobrien CXCursor_ObjCAutoreleasePoolStmt = 221, 201218334Speter 201318334Speter /** \brief Objective-C's collection statement. 201418334Speter */ 201518334Speter CXCursor_ObjCForCollectionStmt = 222, 201618334Speter 201718334Speter /** \brief C++'s catch statement. 201818334Speter */ 201918334Speter CXCursor_CXXCatchStmt = 223, 202018334Speter 202118334Speter /** \brief C++'s try statement. 202218334Speter */ 202318334Speter CXCursor_CXXTryStmt = 224, 202418334Speter 202518334Speter /** \brief C++'s for (* : *) statement. 202618334Speter */ 202718334Speter CXCursor_CXXForRangeStmt = 225, 202818334Speter 202918334Speter /** \brief Windows Structured Exception Handling's try statement. 203018334Speter */ 203118334Speter CXCursor_SEHTryStmt = 226, 203218334Speter 203318334Speter /** \brief Windows Structured Exception Handling's except statement. 203418334Speter */ 203518334Speter CXCursor_SEHExceptStmt = 227, 203618334Speter 203718334Speter /** \brief Windows Structured Exception Handling's finally statement. 203818334Speter */ 203918334Speter CXCursor_SEHFinallyStmt = 228, 204018334Speter 204118334Speter /** \brief A MS inline assembly statement extension. 204218334Speter */ 204318334Speter CXCursor_MSAsmStmt = 229, 204450397Sobrien 204518334Speter /** \brief The null satement ";": C99 6.8.3p3. 204618334Speter * 204718334Speter * This cursor kind is used to describe the null statement. 204818334Speter */ 204918334Speter CXCursor_NullStmt = 230, 205018334Speter 205118334Speter /** \brief Adaptor class for mixing declarations with statements and 205218334Speter * expressions. 205318334Speter */ 205418334Speter CXCursor_DeclStmt = 231, 205518334Speter 205618334Speter CXCursor_LastStmt = CXCursor_DeclStmt, 205718334Speter 205818334Speter /** 205918334Speter * \brief Cursor that represents the translation unit itself. 206018334Speter * 206118334Speter * The translation unit cursor exists primarily to act as the root 206218334Speter * cursor for traversing the contents of a translation unit. 206318334Speter */ 206418334Speter CXCursor_TranslationUnit = 300, 206518334Speter 206618334Speter /* Attributes */ 206718334Speter CXCursor_FirstAttr = 400, 206818334Speter /** 206918334Speter * \brief An attribute whose specific kind is not exposed via this 207018334Speter * interface. 207118334Speter */ 207218334Speter CXCursor_UnexposedAttr = 400, 207318334Speter 207418334Speter CXCursor_IBActionAttr = 401, 207518334Speter CXCursor_IBOutletAttr = 402, 207618334Speter CXCursor_IBOutletCollectionAttr = 403, 207718334Speter CXCursor_CXXFinalAttr = 404, 207818334Speter CXCursor_CXXOverrideAttr = 405, 207918334Speter CXCursor_AnnotateAttr = 406, 208018334Speter CXCursor_AsmLabelAttr = 407, 208118334Speter CXCursor_LastAttr = CXCursor_AsmLabelAttr, 208218334Speter 208318334Speter /* Preprocessing */ 208418334Speter CXCursor_PreprocessingDirective = 500, 208518334Speter CXCursor_MacroDefinition = 501, 208618334Speter CXCursor_MacroExpansion = 502, 208718334Speter CXCursor_MacroInstantiation = CXCursor_MacroExpansion, 208818334Speter CXCursor_InclusionDirective = 503, 208918334Speter CXCursor_FirstPreprocessing = CXCursor_PreprocessingDirective, 209018334Speter CXCursor_LastPreprocessing = CXCursor_InclusionDirective, 209118334Speter 209218334Speter /* Extra Declarations */ 209318334Speter /** 209418334Speter * \brief A module import declaration. 209518334Speter */ 209618334Speter CXCursor_ModuleImportDecl = 600, 209718334Speter CXCursor_FirstExtraDecl = CXCursor_ModuleImportDecl, 209818334Speter CXCursor_LastExtraDecl = CXCursor_ModuleImportDecl 209918334Speter}; 210018334Speter 210118334Speter/** 210218334Speter * \brief A cursor representing some element in the abstract syntax tree for 210318334Speter * a translation unit. 210418334Speter * 210518334Speter * The cursor abstraction unifies the different kinds of entities in a 210618334Speter * program--declaration, statements, expressions, references to declarations, 210718334Speter * etc.--under a single "cursor" abstraction with a common set of operations. 210818334Speter * Common operation for a cursor include: getting the physical location in 210918334Speter * a source file where the cursor points, getting the name associated with a 211018334Speter * cursor, and retrieving cursors for any child nodes of a particular cursor. 211118334Speter * 211218334Speter * Cursors can be produced in two specific ways. 211318334Speter * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 211418334Speter * from which one can use clang_visitChildren() to explore the rest of the 211518334Speter * translation unit. clang_getCursor() maps from a physical source location 211618334Speter * to the entity that resides at that location, allowing one to map from the 211718334Speter * source code into the AST. 211818334Speter */ 211918334Spetertypedef struct { 212018334Speter enum CXCursorKind kind; 212118334Speter int xdata; 212218334Speter const void *data[3]; 212318334Speter} CXCursor; 212418334Speter 212518334Speter/** 212618334Speter * \brief A comment AST node. 212718334Speter */ 212818334Spetertypedef struct { 212918334Speter const void *ASTNode; 213050397Sobrien CXTranslationUnit TranslationUnit; 213150397Sobrien} CXComment; 213250397Sobrien 213350397Sobrien/** 213450397Sobrien * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations 213550397Sobrien * 213650397Sobrien * @{ 213750397Sobrien */ 213850397Sobrien 213950397Sobrien/** 214050397Sobrien * \brief Retrieve the NULL cursor, which represents no entity. 214150397Sobrien */ 214250397SobrienCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 214350397Sobrien 214450397Sobrien/** 214550397Sobrien * \brief Retrieve the cursor that represents the given translation unit. 214650397Sobrien * 214750397Sobrien * The translation unit cursor can be used to start traversing the 214850397Sobrien * various declarations within the given translation unit. 214950397Sobrien */ 215050397SobrienCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 215150397Sobrien 215250397Sobrien/** 215350397Sobrien * \brief Determine whether two cursors are equivalent. 215450397Sobrien */ 215550397SobrienCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 215650397Sobrien 215750397Sobrien/** 215850397Sobrien * \brief Returns non-zero if \p cursor is null. 215950397Sobrien */ 216050397SobrienCINDEX_LINKAGE int clang_Cursor_isNull(CXCursor cursor); 216150397Sobrien 216250397Sobrien/** 216350397Sobrien * \brief Compute a hash value for the given cursor. 216450397Sobrien */ 216550397SobrienCINDEX_LINKAGE unsigned clang_hashCursor(CXCursor); 216650397Sobrien 216750397Sobrien/** 216850397Sobrien * \brief Retrieve the kind of the given cursor. 216950397Sobrien */ 217050397SobrienCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 217150397Sobrien 217250397Sobrien/** 217350397Sobrien * \brief Determine whether the given cursor kind represents a declaration. 217450397Sobrien */ 217550397SobrienCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 217650397Sobrien 217750397Sobrien/** 217850397Sobrien * \brief Determine whether the given cursor kind represents a simple 217950397Sobrien * reference. 218050397Sobrien * 218150397Sobrien * Note that other kinds of cursors (such as expressions) can also refer to 218250397Sobrien * other cursors. Use clang_getCursorReferenced() to determine whether a 218350397Sobrien * particular cursor refers to another entity. 218450397Sobrien */ 218550397SobrienCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 218650397Sobrien 218750397Sobrien/** 218850397Sobrien * \brief Determine whether the given cursor kind represents an expression. 218950397Sobrien */ 219050397SobrienCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 219150397Sobrien 219250397Sobrien/** 219350397Sobrien * \brief Determine whether the given cursor kind represents a statement. 219418334Speter */ 219518334SpeterCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 219618334Speter 219718334Speter/** 219818334Speter * \brief Determine whether the given cursor kind represents an attribute. 219918334Speter */ 220018334SpeterCINDEX_LINKAGE unsigned clang_isAttribute(enum CXCursorKind); 220152284Sobrien 220218334Speter/** 220318334Speter * \brief Determine whether the given cursor kind represents an invalid 220418334Speter * cursor. 220518334Speter */ 220618334SpeterCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 220718334Speter 220818334Speter/** 220918334Speter * \brief Determine whether the given cursor kind represents a translation 221052284Sobrien * unit. 221118334Speter */ 221218334SpeterCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 221318334Speter 221418334Speter/*** 221552284Sobrien * \brief Determine whether the given cursor represents a preprocessing 221618334Speter * element, such as a preprocessor directive or macro instantiation. 221718334Speter */ 221818334SpeterCINDEX_LINKAGE unsigned clang_isPreprocessing(enum CXCursorKind); 221918334Speter 222018334Speter/*** 222118334Speter * \brief Determine whether the given cursor represents a currently 222218334Speter * unexposed piece of the AST (e.g., CXCursor_UnexposedStmt). 222318334Speter */ 222418334SpeterCINDEX_LINKAGE unsigned clang_isUnexposed(enum CXCursorKind); 222518334Speter 222618334Speter/** 222718334Speter * \brief Describe the linkage of the entity referred to by a cursor. 222818334Speter */ 222952284Sobrienenum CXLinkageKind { 223018334Speter /** \brief This value indicates that no linkage information is available 223118334Speter * for a provided CXCursor. */ 223218334Speter CXLinkage_Invalid, 223318334Speter /** 223450397Sobrien * \brief This is the linkage for variables, parameters, and so on that 223552284Sobrien * have automatic storage. This covers normal (non-extern) local variables. 223652284Sobrien */ 223752284Sobrien CXLinkage_NoLinkage, 223818334Speter /** \brief This is the linkage for static variables and static functions. */ 223952284Sobrien CXLinkage_Internal, 224052284Sobrien /** \brief This is the linkage for entities with external linkage that live 224152284Sobrien * in C++ anonymous namespaces.*/ 224252284Sobrien CXLinkage_UniqueExternal, 224352284Sobrien /** \brief This is the linkage for entities with true, external linkage. */ 224452284Sobrien CXLinkage_External 224518334Speter}; 224618334Speter 224750397Sobrien/** 224852284Sobrien * \brief Determine the linkage of the entity referred to by a given cursor. 224952284Sobrien */ 225052284SobrienCINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage(CXCursor cursor); 225118334Speter 225252284Sobrien/** 225352284Sobrien * \brief Determine the availability of the entity that this cursor refers to, 225418334Speter * taking the current target platform into account. 225518334Speter * 225618334Speter * \param cursor The cursor to query. 225718334Speter * 225818334Speter * \returns The availability of the cursor. 225918334Speter */ 226018334SpeterCINDEX_LINKAGE enum CXAvailabilityKind 226118334Speterclang_getCursorAvailability(CXCursor cursor); 226218334Speter 226318334Speter/** 226418334Speter * Describes the availability of a given entity on a particular platform, e.g., 226518334Speter * a particular class might only be available on Mac OS 10.7 or newer. 226618334Speter */ 226718334Spetertypedef struct CXPlatformAvailability { 226818334Speter /** 226918334Speter * \brief A string that describes the platform for which this structure 227018334Speter * provides availability information. 227118334Speter * 227218334Speter * Possible values are "ios" or "macosx". 227318334Speter */ 227418334Speter CXString Platform; 227518334Speter /** 227618334Speter * \brief The version number in which this entity was introduced. 227718334Speter */ 227818334Speter CXVersion Introduced; 227918334Speter /** 228018334Speter * \brief The version number in which this entity was deprecated (but is 228118334Speter * still available). 228218334Speter */ 228318334Speter CXVersion Deprecated; 228418334Speter /** 228518334Speter * \brief The version number in which this entity was obsoleted, and therefore 228618334Speter * is no longer available. 228718334Speter */ 228818334Speter CXVersion Obsoleted; 228918334Speter /** 229018334Speter * \brief Whether the entity is unconditionally unavailable on this platform. 229118334Speter */ 229218334Speter int Unavailable; 229318334Speter /** 229452284Sobrien * \brief An optional message to provide to a user of this API, e.g., to 229552284Sobrien * suggest replacement APIs. 229618334Speter */ 229718334Speter CXString Message; 229818334Speter} CXPlatformAvailability; 229918334Speter 230018334Speter/** 230118334Speter * \brief Determine the availability of the entity that this cursor refers to 230218334Speter * on any platforms for which availability information is known. 230318334Speter * 230418334Speter * \param cursor The cursor to query. 230518334Speter * 230618334Speter * \param always_deprecated If non-NULL, will be set to indicate whether the 230718334Speter * entity is deprecated on all platforms. 230818334Speter * 230918334Speter * \param deprecated_message If non-NULL, will be set to the message text 231018334Speter * provided along with the unconditional deprecation of this entity. The client 231118334Speter * is responsible for deallocating this string. 231218334Speter * 231318334Speter * \param always_unavailable If non-NULL, will be set to indicate whether the 231418334Speter * entity is unavailable on all platforms. 231518334Speter * 231618334Speter * \param unavailable_message If non-NULL, will be set to the message text 231718334Speter * provided along with the unconditional unavailability of this entity. The 231818334Speter * client is responsible for deallocating this string. 231918334Speter * 232018334Speter * \param availability If non-NULL, an array of CXPlatformAvailability instances 232118334Speter * that will be populated with platform availability information, up to either 232218334Speter * the number of platforms for which availability information is available (as 232352284Sobrien * returned by this function) or \c availability_size, whichever is smaller. 232452284Sobrien * 232552284Sobrien * \param availability_size The number of elements available in the 232652284Sobrien * \c availability array. 232752284Sobrien * 232818334Speter * \returns The number of platforms (N) for which availability information is 232918334Speter * available (which is unrelated to \c availability_size). 233018334Speter * 233118334Speter * Note that the client is responsible for calling 233218334Speter * \c clang_disposeCXPlatformAvailability to free each of the 233352284Sobrien * platform-availability structures returned. There are 233450397Sobrien * \c min(N, availability_size) such structures. 233518334Speter */ 233652284SobrienCINDEX_LINKAGE int 233718334Speterclang_getCursorPlatformAvailability(CXCursor cursor, 233818334Speter int *always_deprecated, 233918334Speter CXString *deprecated_message, 234018334Speter int *always_unavailable, 234152284Sobrien CXString *unavailable_message, 234218334Speter CXPlatformAvailability *availability, 234352284Sobrien int availability_size); 234418334Speter 234552284Sobrien/** 234650397Sobrien * \brief Free the memory associated with a \c CXPlatformAvailability structure. 234718334Speter */ 234818334SpeterCINDEX_LINKAGE void 234918334Speterclang_disposeCXPlatformAvailability(CXPlatformAvailability *availability); 235018334Speter 235152284Sobrien/** 235218334Speter * \brief Describe the "language" of the entity referred to by a cursor. 235318334Speter */ 235418334SpeterCINDEX_LINKAGE enum CXLanguageKind { 235518334Speter CXLanguage_Invalid = 0, 235618334Speter CXLanguage_C, 235718334Speter CXLanguage_ObjC, 235818334Speter CXLanguage_CPlusPlus 235918334Speter}; 236018334Speter 236118334Speter/** 236218334Speter * \brief Determine the "language" of the entity referred to by a given cursor. 236318334Speter */ 236418334SpeterCINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage(CXCursor cursor); 236550397Sobrien 236618334Speter/** 236752284Sobrien * \brief Returns the translation unit that a cursor originated from. 236852284Sobrien */ 236918334SpeterCINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit(CXCursor); 237052284Sobrien 237118334Speter 237218334Speter/** 237318334Speter * \brief A fast container representing a set of CXCursors. 237418334Speter */ 237552284Sobrientypedef struct CXCursorSetImpl *CXCursorSet; 237618334Speter 237718334Speter/** 237818334Speter * \brief Creates an empty CXCursorSet. 237918334Speter */ 238018334SpeterCINDEX_LINKAGE CXCursorSet clang_createCXCursorSet(void); 238118334Speter 238218334Speter/** 238318334Speter * \brief Disposes a CXCursorSet and releases its associated memory. 238418334Speter */ 238518334SpeterCINDEX_LINKAGE void clang_disposeCXCursorSet(CXCursorSet cset); 238618334Speter 238718334Speter/** 238818334Speter * \brief Queries a CXCursorSet to see if it contains a specific CXCursor. 238918334Speter * 239018334Speter * \returns non-zero if the set contains the specified cursor. 239118334Speter*/ 239218334SpeterCINDEX_LINKAGE unsigned clang_CXCursorSet_contains(CXCursorSet cset, 239318334Speter CXCursor cursor); 239418334Speter 239518334Speter/** 239618334Speter * \brief Inserts a CXCursor into a CXCursorSet. 239718334Speter * 239818334Speter * \returns zero if the CXCursor was already in the set, and non-zero otherwise. 239918334Speter*/ 240018334SpeterCINDEX_LINKAGE unsigned clang_CXCursorSet_insert(CXCursorSet cset, 240118334Speter CXCursor cursor); 240218334Speter 240318334Speter/** 240418334Speter * \brief Determine the semantic parent of the given cursor. 240550397Sobrien * 240618334Speter * The semantic parent of a cursor is the cursor that semantically contains 240752284Sobrien * the given \p cursor. For many declarations, the lexical and semantic parents 240852284Sobrien * are equivalent (the lexical parent is returned by 240918334Speter * \c clang_getCursorLexicalParent()). They diverge when declarations or 241018334Speter * definitions are provided out-of-line. For example: 241150397Sobrien * 241218334Speter * \code 241318334Speter * class C { 241418334Speter * void f(); 241552284Sobrien * }; 241618334Speter * 241718334Speter * void C::f() { } 241852284Sobrien * \endcode 241918334Speter * 242052284Sobrien * In the out-of-line definition of \c C::f, the semantic parent is the 242152284Sobrien * the class \c C, of which this function is a member. The lexical parent is 242218334Speter * the place where the declaration actually occurs in the source code; in this 242318334Speter * case, the definition occurs in the translation unit. In general, the 242418334Speter * lexical parent for a given entity can change without affecting the semantics 242518334Speter * of the program, and the lexical parent of different declarations of the 242618334Speter * same entity may be different. Changing the semantic parent of a declaration, 242718334Speter * on the other hand, can have a major impact on semantics, and redeclarations 242818334Speter * of a particular entity should all have the same semantic context. 242918334Speter * 243018334Speter * In the example above, both declarations of \c C::f have \c C as their 243118334Speter * semantic context, while the lexical context of the first \c C::f is \c C 243218334Speter * and the lexical context of the second \c C::f is the translation unit. 243318334Speter * 243450397Sobrien * For global declarations, the semantic parent is the translation unit. 243518334Speter */ 243618334SpeterCINDEX_LINKAGE CXCursor clang_getCursorSemanticParent(CXCursor cursor); 243718334Speter 243818334Speter/** 243918334Speter * \brief Determine the lexical parent of the given cursor. 244018334Speter * 244118334Speter * The lexical parent of a cursor is the cursor in which the given \p cursor 244252284Sobrien * was actually written. For many declarations, the lexical and semantic parents 244318334Speter * are equivalent (the semantic parent is returned by 244418334Speter * \c clang_getCursorSemanticParent()). They diverge when declarations or 244518334Speter * definitions are provided out-of-line. For example: 244618334Speter * 244718334Speter * \code 244818334Speter * class C { 244918334Speter * void f(); 245018334Speter * }; 245118334Speter * 245218334Speter * void C::f() { } 245318334Speter * \endcode 245418334Speter * 245518334Speter * In the out-of-line definition of \c C::f, the semantic parent is the 245618334Speter * the class \c C, of which this function is a member. The lexical parent is 245718334Speter * the place where the declaration actually occurs in the source code; in this 245852284Sobrien * case, the definition occurs in the translation unit. In general, the 245918334Speter * lexical parent for a given entity can change without affecting the semantics 246018334Speter * of the program, and the lexical parent of different declarations of the 246118334Speter * same entity may be different. Changing the semantic parent of a declaration, 246218334Speter * on the other hand, can have a major impact on semantics, and redeclarations 246352284Sobrien * of a particular entity should all have the same semantic context. 246418334Speter * 246518334Speter * In the example above, both declarations of \c C::f have \c C as their 246652284Sobrien * semantic context, while the lexical context of the first \c C::f is \c C 246718334Speter * and the lexical context of the second \c C::f is the translation unit. 246818334Speter * 246918334Speter * For declarations written in the global scope, the lexical parent is 247018334Speter * the translation unit. 247118334Speter */ 247252284SobrienCINDEX_LINKAGE CXCursor clang_getCursorLexicalParent(CXCursor cursor); 247352284Sobrien 247418334Speter/** 247518334Speter * \brief Determine the set of methods that are overridden by the given 247618334Speter * method. 247718334Speter * 247852284Sobrien * In both Objective-C and C++, a method (aka virtual member function, 247918334Speter * in C++) can override a virtual method in a base class. For 248052284Sobrien * Objective-C, a method is said to override any method in the class's 248152284Sobrien * base class, its protocols, or its categories' protocols, that has the same 248218334Speter * selector and is of the same kind (class or instance). 248352284Sobrien * If no such method exists, the search continues to the class's superclass, 248418334Speter * its protocols, and its categories, and so on. A method from an Objective-C 248518334Speter * implementation is considered to override the same methods as its 248618334Speter * corresponding method in the interface. 248718334Speter * 248818334Speter * For C++, a virtual member function overrides any virtual member 248918334Speter * function with the same signature that occurs in its base 249018334Speter * classes. With multiple inheritance, a virtual member function can 249118334Speter * override several virtual member functions coming from different 249218334Speter * base classes. 249350397Sobrien * 249418334Speter * In all cases, this function determines the immediate overridden 249518334Speter * method, rather than all of the overridden methods. For example, if 249618334Speter * a method is originally declared in a class A, then overridden in B 249718334Speter * (which in inherits from A) and also in C (which inherited from B), 249818334Speter * then the only overridden method returned from this function when 249918334Speter * invoked on C's method will be B's method. The client may then 250018334Speter * invoke this function again, given the previously-found overridden 250118334Speter * methods, to map out the complete method-override set. 250218334Speter * 250318334Speter * \param cursor A cursor representing an Objective-C or C++ 250418334Speter * method. This routine will compute the set of methods that this 250518334Speter * method overrides. 250618334Speter * 250718334Speter * \param overridden A pointer whose pointee will be replaced with a 250818334Speter * pointer to an array of cursors, representing the set of overridden 250918334Speter * methods. If there are no overridden methods, the pointee will be 251018334Speter * set to NULL. The pointee must be freed via a call to 251118334Speter * \c clang_disposeOverriddenCursors(). 251218334Speter * 251318334Speter * \param num_overridden A pointer to the number of overridden 251418334Speter * functions, will be set to the number of overridden functions in the 251518334Speter * array pointed to by \p overridden. 251618334Speter */ 251718334SpeterCINDEX_LINKAGE void clang_getOverriddenCursors(CXCursor cursor, 251818334Speter CXCursor **overridden, 251918334Speter unsigned *num_overridden); 252018334Speter 252118334Speter/** 252218334Speter * \brief Free the set of overridden cursors returned by \c 252318334Speter * clang_getOverriddenCursors(). 252418334Speter */ 252518334SpeterCINDEX_LINKAGE void clang_disposeOverriddenCursors(CXCursor *overridden); 252618334Speter 252718334Speter/** 252818334Speter * \brief Retrieve the file that is included by the given inclusion directive 252950397Sobrien * cursor. 253018334Speter */ 253152284SobrienCINDEX_LINKAGE CXFile clang_getIncludedFile(CXCursor cursor); 253218334Speter 253352284Sobrien/** 253418334Speter * @} 253518334Speter */ 253618334Speter 253718334Speter/** 253850397Sobrien * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code 253918334Speter * 254052284Sobrien * Cursors represent a location within the Abstract Syntax Tree (AST). These 254118334Speter * routines help map between cursors and the physical locations where the 254218334Speter * described entities occur in the source code. The mapping is provided in 254318334Speter * both directions, so one can map from source code to the AST and back. 254418334Speter * 254518334Speter * @{ 254618334Speter */ 254718334Speter 254852284Sobrien/** 254952284Sobrien * \brief Map a source location to the cursor that describes the entity at that 255052284Sobrien * location in the source code. 255152284Sobrien * 255252284Sobrien * clang_getCursor() maps an arbitrary source location within a translation 255352284Sobrien * unit down to the most specific cursor that describes the entity at that 255452284Sobrien * location. For example, given an expression \c x + y, invoking 255552284Sobrien * clang_getCursor() with a source location pointing to "x" will return the 255618334Speter * cursor for "x"; similarly for "y". If the cursor points anywhere between 255718334Speter * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() 255818334Speter * will return a cursor referring to the "+" expression. 255918334Speter * 256018334Speter * \returns a cursor representing the entity at the given source location, or 256118334Speter * a NULL cursor if no such entity can be found. 256250397Sobrien */ 256318334SpeterCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); 256418334Speter 256518334Speter/** 256618334Speter * \brief Retrieve the physical location of the source constructor referenced 256718334Speter * by the given cursor. 256818334Speter * 256918334Speter * The location of a declaration is typically the location of the name of that 257050397Sobrien * declaration, where the name of that declaration would occur if it is 257118334Speter * unnamed, or some keyword that introduces that particular declaration. 257218334Speter * The location of a reference is where that reference occurs within the 257318334Speter * source code. 257418334Speter */ 257518334SpeterCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 257618334Speter 257718334Speter/** 257818334Speter * \brief Retrieve the physical extent of the source construct referenced by 257918334Speter * the given cursor. 258018334Speter * 258118334Speter * The extent of a cursor starts with the file/line/column pointing at the 258218334Speter * first character within the source construct that the cursor refers to and 258318334Speter * ends with the last character withinin that source construct. For a 258418334Speter * declaration, the extent covers the declaration itself. For a reference, 258518334Speter * the extent covers the location of the reference (e.g., where the referenced 258618334Speter * entity was actually used). 258718334Speter */ 258818334SpeterCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 258918334Speter 259018334Speter/** 259118334Speter * @} 259218334Speter */ 259350397Sobrien 259418334Speter/** 259518334Speter * \defgroup CINDEX_TYPES Type information for CXCursors 259618334Speter * 259718334Speter * @{ 259818334Speter */ 259918334Speter 260018334Speter/** 260118334Speter * \brief Describes the kind of type 260218334Speter */ 260318334Speterenum CXTypeKind { 260418334Speter /** 260518334Speter * \brief Reprents an invalid type (e.g., where no type is available). 260618334Speter */ 260718334Speter CXType_Invalid = 0, 260818334Speter 260918334Speter /** 261018334Speter * \brief A type whose specific kind is not exposed via this 261150397Sobrien * interface. 261218334Speter */ 261318334Speter CXType_Unexposed = 1, 261418334Speter 261518334Speter /* Builtin types */ 261618334Speter CXType_Void = 2, 261718334Speter CXType_Bool = 3, 261818334Speter CXType_Char_U = 4, 261918334Speter CXType_UChar = 5, 262018334Speter CXType_Char16 = 6, 262150397Sobrien CXType_Char32 = 7, 262218334Speter CXType_UShort = 8, 262318334Speter CXType_UInt = 9, 262418334Speter CXType_ULong = 10, 262518334Speter CXType_ULongLong = 11, 262618334Speter CXType_UInt128 = 12, 262718334Speter CXType_Char_S = 13, 262818334Speter CXType_SChar = 14, 262950397Sobrien CXType_WChar = 15, 263018334Speter CXType_Short = 16, 263118334Speter CXType_Int = 17, 263250397Sobrien CXType_Long = 18, 263318334Speter CXType_LongLong = 19, 263418334Speter CXType_Int128 = 20, 263518334Speter CXType_Float = 21, 263618334Speter CXType_Double = 22, 263718334Speter CXType_LongDouble = 23, 263818334Speter CXType_NullPtr = 24, 263918334Speter CXType_Overload = 25, 264018334Speter CXType_Dependent = 26, 264118334Speter CXType_ObjCId = 27, 264218334Speter CXType_ObjCClass = 28, 264352284Sobrien CXType_ObjCSel = 29, 264452284Sobrien CXType_FirstBuiltin = CXType_Void, 264552284Sobrien CXType_LastBuiltin = CXType_ObjCSel, 264652284Sobrien 264718334Speter CXType_Complex = 100, 264818334Speter CXType_Pointer = 101, 264918334Speter CXType_BlockPointer = 102, 265050397Sobrien CXType_LValueReference = 103, 265118334Speter CXType_RValueReference = 104, 265252284Sobrien CXType_Record = 105, 265352284Sobrien CXType_Enum = 106, 265452284Sobrien CXType_Typedef = 107, 265552284Sobrien CXType_ObjCInterface = 108, 265652284Sobrien CXType_ObjCObjectPointer = 109, 265718334Speter CXType_FunctionNoProto = 110, 265852284Sobrien CXType_FunctionProto = 111, 265952284Sobrien CXType_ConstantArray = 112, 266052284Sobrien CXType_Vector = 113 266152284Sobrien}; 266252284Sobrien 266318334Speter/** 266452284Sobrien * \brief Describes the calling convention of a function type 266552284Sobrien */ 266618334Speterenum CXCallingConv { 266752284Sobrien CXCallingConv_Default = 0, 266852284Sobrien CXCallingConv_C = 1, 266952284Sobrien CXCallingConv_X86StdCall = 2, 267018334Speter CXCallingConv_X86FastCall = 3, 267152284Sobrien CXCallingConv_X86ThisCall = 4, 267218334Speter CXCallingConv_X86Pascal = 5, 267350397Sobrien CXCallingConv_AAPCS = 6, 267418334Speter CXCallingConv_AAPCS_VFP = 7, 267552284Sobrien CXCallingConv_PnaclCall = 8, 267652284Sobrien CXCallingConv_IntelOclBicc = 9, 267752284Sobrien 267852284Sobrien CXCallingConv_Invalid = 100, 267952284Sobrien CXCallingConv_Unexposed = 200 268052284Sobrien}; 268152284Sobrien 268252284Sobrien 268318334Speter/** 268450397Sobrien * \brief The type of an element in the abstract syntax tree. 268518334Speter * 268618334Speter */ 268718334Spetertypedef struct { 268818334Speter enum CXTypeKind kind; 268918334Speter void *data[2]; 269018334Speter} CXType; 269118334Speter 269218334Speter/** 269318334Speter * \brief Retrieve the type of a CXCursor (if any). 269418334Speter */ 269518334SpeterCINDEX_LINKAGE CXType clang_getCursorType(CXCursor C); 269618334Speter 269718334Speter/** 269818334Speter * \brief Pretty-print the underlying type using the rules of the 269918334Speter * language of the translation unit from which it came. 270050397Sobrien * 270118334Speter * If the type is invalid, an empty string is returned. 270218334Speter */ 270318334SpeterCINDEX_LINKAGE CXString clang_getTypeSpelling(CXType CT); 270418334Speter 270518334Speter/** 270618334Speter * \brief Retrieve the underlying type of a typedef declaration. 270718334Speter * 270818334Speter * If the cursor does not reference a typedef declaration, an invalid type is 270918334Speter * returned. 271018334Speter */ 271118334SpeterCINDEX_LINKAGE CXType clang_getTypedefDeclUnderlyingType(CXCursor C); 271218334Speter 271318334Speter/** 271418334Speter * \brief Retrieve the integer type of an enum declaration. 271518334Speter * 271618334Speter * If the cursor does not reference an enum declaration, an invalid type is 271718334Speter * returned. 271818334Speter */ 271918334SpeterCINDEX_LINKAGE CXType clang_getEnumDeclIntegerType(CXCursor C); 272018334Speter 272118334Speter/** 272218334Speter * \brief Retrieve the integer value of an enum constant declaration as a signed 272318334Speter * long long. 272418334Speter * 272518334Speter * If the cursor does not reference an enum constant declaration, LLONG_MIN is returned. 272618334Speter * Since this is also potentially a valid constant value, the kind of the cursor 272718334Speter * must be verified before calling this function. 272818334Speter */ 272918334SpeterCINDEX_LINKAGE long long clang_getEnumConstantDeclValue(CXCursor C); 273018334Speter 273118334Speter/** 273218334Speter * \brief Retrieve the integer value of an enum constant declaration as an unsigned 273318334Speter * long long. 273418334Speter * 273518334Speter * If the cursor does not reference an enum constant declaration, ULLONG_MAX is returned. 273618334Speter * Since this is also potentially a valid constant value, the kind of the cursor 273718334Speter * must be verified before calling this function. 273818334Speter */ 273918334SpeterCINDEX_LINKAGE unsigned long long clang_getEnumConstantDeclUnsignedValue(CXCursor C); 274018334Speter 274118334Speter/** 274250397Sobrien * \brief Retrieve the bit width of a bit field declaration as an integer. 274318334Speter * 274418334Speter * If a cursor that is not a bit field declaration is passed in, -1 is returned. 274518334Speter */ 274618334SpeterCINDEX_LINKAGE int clang_getFieldDeclBitWidth(CXCursor C); 274718334Speter 274818334Speter/** 274918334Speter * \brief Retrieve the number of non-variadic arguments associated with a given 275018334Speter * cursor. 275150397Sobrien * 275218334Speter * The number of arguments can be determined for calls as well as for 275318334Speter * declarations of functions or methods. For other cursors -1 is returned. 275418334Speter */ 275518334SpeterCINDEX_LINKAGE int clang_Cursor_getNumArguments(CXCursor C); 275618334Speter 275718334Speter/** 275818334Speter * \brief Retrieve the argument cursor of a function or method. 275950397Sobrien * 276018334Speter * The argument cursor can be determined for calls as well as for declarations 276118334Speter * of functions or methods. For other cursors and for invalid indices, an 276218334Speter * invalid cursor is returned. 276318334Speter */ 276418334SpeterCINDEX_LINKAGE CXCursor clang_Cursor_getArgument(CXCursor C, unsigned i); 276518334Speter 276618334Speter/** 276718334Speter * \brief Determine whether two CXTypes represent the same type. 276818334Speter * 276918334Speter * \returns non-zero if the CXTypes represent the same type and 277018334Speter * zero otherwise. 277118334Speter */ 277218334SpeterCINDEX_LINKAGE unsigned clang_equalTypes(CXType A, CXType B); 277318334Speter 277418334Speter/** 277518334Speter * \brief Return the canonical type for a CXType. 277618334Speter * 277718334Speter * Clang's type system explicitly models typedefs and all the ways 277818334Speter * a specific type can be represented. The canonical type is the underlying 277950397Sobrien * type with all the "sugar" removed. For example, if 'T' is a typedef 278018334Speter * for 'int', the canonical type for 'T' would be 'int'. 278118334Speter */ 278218334SpeterCINDEX_LINKAGE CXType clang_getCanonicalType(CXType T); 278318334Speter 278418334Speter/** 278518334Speter * \brief Determine whether a CXType has the "const" qualifier set, 278618334Speter * without looking through typedefs that may have added "const" at a 278718334Speter * different level. 278818334Speter */ 278918334SpeterCINDEX_LINKAGE unsigned clang_isConstQualifiedType(CXType T); 279018334Speter 279118334Speter/** 279250397Sobrien * \brief Determine whether a CXType has the "volatile" qualifier set, 279318334Speter * without looking through typedefs that may have added "volatile" at 279418334Speter * a different level. 279518334Speter */ 279618334SpeterCINDEX_LINKAGE unsigned clang_isVolatileQualifiedType(CXType T); 279718334Speter 279818334Speter/** 279918334Speter * \brief Determine whether a CXType has the "restrict" qualifier set, 280018334Speter * without looking through typedefs that may have added "restrict" at a 280118334Speter * different level. 280218334Speter */ 280318334SpeterCINDEX_LINKAGE unsigned clang_isRestrictQualifiedType(CXType T); 280418334Speter 280518334Speter/** 280618334Speter * \brief For pointer types, returns the type of the pointee. 280718334Speter */ 280818334SpeterCINDEX_LINKAGE CXType clang_getPointeeType(CXType T); 280950397Sobrien 281018334Speter/** 281118334Speter * \brief Return the cursor for the declaration of the given type. 281218334Speter */ 281318334SpeterCINDEX_LINKAGE CXCursor clang_getTypeDeclaration(CXType T); 281418334Speter 281518334Speter/** 281618334Speter * Returns the Objective-C type encoding for the specified declaration. 281718334Speter */ 281850397SobrienCINDEX_LINKAGE CXString clang_getDeclObjCTypeEncoding(CXCursor C); 281918334Speter 282018334Speter/** 282118334Speter * \brief Retrieve the spelling of a given CXTypeKind. 282218334Speter */ 282318334SpeterCINDEX_LINKAGE CXString clang_getTypeKindSpelling(enum CXTypeKind K); 282418334Speter 282518334Speter/** 282618334Speter * \brief Retrieve the calling convention associated with a function type. 282718334Speter * 282818334Speter * If a non-function type is passed in, CXCallingConv_Invalid is returned. 282918334Speter */ 283018334SpeterCINDEX_LINKAGE enum CXCallingConv clang_getFunctionTypeCallingConv(CXType T); 283118334Speter 283218334Speter/** 283318334Speter * \brief Retrieve the result type associated with a function type. 283418334Speter * 283518334Speter * If a non-function type is passed in, an invalid type is returned. 283618334Speter */ 283718334SpeterCINDEX_LINKAGE CXType clang_getResultType(CXType T); 283818334Speter 283918334Speter/** 284018334Speter * \brief Retrieve the number of non-variadic arguments associated with a 284118334Speter * function type. 284218334Speter * 284350397Sobrien * If a non-function type is passed in, -1 is returned. 284418334Speter */ 284518334SpeterCINDEX_LINKAGE int clang_getNumArgTypes(CXType T); 284618334Speter 284718334Speter/** 284818334Speter * \brief Retrieve the type of an argument of a function type. 284918334Speter * 285018334Speter * If a non-function type is passed in or the function does not have enough 285118334Speter * parameters, an invalid type is returned. 285218334Speter */ 285318334SpeterCINDEX_LINKAGE CXType clang_getArgType(CXType T, unsigned i); 285450397Sobrien 285518334Speter/** 285652284Sobrien * \brief Return 1 if the CXType is a variadic function type, and 0 otherwise. 285718334Speter */ 285818334SpeterCINDEX_LINKAGE unsigned clang_isFunctionTypeVariadic(CXType T); 285918334Speter 286050397Sobrien/** 286150397Sobrien * \brief Retrieve the result type associated with a given cursor. 286250397Sobrien * 286350397Sobrien * This only returns a valid type if the cursor refers to a function or method. 286450397Sobrien */ 286550397SobrienCINDEX_LINKAGE CXType clang_getCursorResultType(CXCursor C); 286618334Speter 286750397Sobrien/** 286850397Sobrien * \brief Return 1 if the CXType is a POD (plain old data) type, and 0 286950397Sobrien * otherwise. 287050397Sobrien */ 287150397SobrienCINDEX_LINKAGE unsigned clang_isPODType(CXType T); 287218334Speter 287350397Sobrien/** 287450397Sobrien * \brief Return the element type of an array, complex, or vector type. 287518334Speter * 287618334Speter * If a type is passed in that is not an array, complex, or vector type, 287718334Speter * an invalid type is returned. 287818334Speter */ 287918334SpeterCINDEX_LINKAGE CXType clang_getElementType(CXType T); 288018334Speter 288118334Speter/** 288218334Speter * \brief Return the number of elements of an array or vector type. 288318334Speter * 288450397Sobrien * If a type is passed in that is not an array or vector type, 288518334Speter * -1 is returned. 288618334Speter */ 288718334SpeterCINDEX_LINKAGE long long clang_getNumElements(CXType T); 288818334Speter 288950397Sobrien/** 289018334Speter * \brief Return the element type of an array type. 289118334Speter * 289218334Speter * If a non-array type is passed in, an invalid type is returned. 289318334Speter */ 289418334SpeterCINDEX_LINKAGE CXType clang_getArrayElementType(CXType T); 289518334Speter 289618334Speter/** 289718334Speter * \brief Return the array size of a constant array. 289850397Sobrien * 289918334Speter * If a non-array type is passed in, -1 is returned. 290018334Speter */ 290118334SpeterCINDEX_LINKAGE long long clang_getArraySize(CXType T); 290218334Speter 290318334Speter/** 290418334Speter * \brief Returns 1 if the base class specified by the cursor with kind 290550397Sobrien * CX_CXXBaseSpecifier is virtual. 290618334Speter */ 290718334SpeterCINDEX_LINKAGE unsigned clang_isVirtualBase(CXCursor); 290818334Speter 290918334Speter/** 291018334Speter * \brief Represents the C++ access control level to a base class for a 291118334Speter * cursor with kind CX_CXXBaseSpecifier. 291218334Speter */ 291318334Speterenum CX_CXXAccessSpecifier { 291450397Sobrien CX_CXXInvalidAccessSpecifier, 291550397Sobrien CX_CXXPublic, 291618334Speter CX_CXXProtected, 291718334Speter CX_CXXPrivate 291818334Speter}; 291918334Speter 292018334Speter/** 292118334Speter * \brief Returns the access control level for the C++ base specifier 292218334Speter * represented by a cursor with kind CXCursor_CXXBaseSpecifier or 292318334Speter * CXCursor_AccessSpecifier. 292450397Sobrien */ 292518334SpeterCINDEX_LINKAGE enum CX_CXXAccessSpecifier clang_getCXXAccessSpecifier(CXCursor); 292618334Speter 292718334Speter/** 292818334Speter * \brief Determine the number of overloaded declarations referenced by a 292918334Speter * \c CXCursor_OverloadedDeclRef cursor. 293018334Speter * 293118334Speter * \param cursor The cursor whose overloaded declarations are being queried. 293218334Speter * 293318334Speter * \returns The number of overloaded declarations referenced by \c cursor. If it 293418334Speter * is not a \c CXCursor_OverloadedDeclRef cursor, returns 0. 293518334Speter */ 293618334SpeterCINDEX_LINKAGE unsigned clang_getNumOverloadedDecls(CXCursor cursor); 293718334Speter 293818334Speter/** 293918334Speter * \brief Retrieve a cursor for one of the overloaded declarations referenced 294018334Speter * by a \c CXCursor_OverloadedDeclRef cursor. 294118334Speter * 294218334Speter * \param cursor The cursor whose overloaded declarations are being queried. 294318334Speter * 294418334Speter * \param index The zero-based index into the set of overloaded declarations in 294518334Speter * the cursor. 294618334Speter * 294718334Speter * \returns A cursor representing the declaration referenced by the given 294818334Speter * \c cursor at the specified \c index. If the cursor does not have an 294918334Speter * associated set of overloaded declarations, or if the index is out of bounds, 295018334Speter * returns \c clang_getNullCursor(); 295118334Speter */ 295218334SpeterCINDEX_LINKAGE CXCursor clang_getOverloadedDecl(CXCursor cursor, 295318334Speter unsigned index); 295418334Speter 295518334Speter/** 295618334Speter * @} 295718334Speter */ 295818334Speter 295918334Speter/** 296018334Speter * \defgroup CINDEX_ATTRIBUTES Information for attributes 296118334Speter * 296218334Speter * @{ 296350397Sobrien */ 296418334Speter 296518334Speter 296618334Speter/** 296718334Speter * \brief For cursors representing an iboutletcollection attribute, 296818334Speter * this function returns the collection element type. 296918334Speter * 297018334Speter */ 297118334SpeterCINDEX_LINKAGE CXType clang_getIBOutletCollectionType(CXCursor); 297218334Speter 297318334Speter/** 297418334Speter * @} 297518334Speter */ 297618334Speter 297718334Speter/** 297818334Speter * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors 297918334Speter * 298018334Speter * These routines provide the ability to traverse the abstract syntax tree 298118334Speter * using cursors. 298218334Speter * 298318334Speter * @{ 298418334Speter */ 298518334Speter 298618334Speter/** 298718334Speter * \brief Describes how the traversal of the children of a particular 298818334Speter * cursor should proceed after visiting a particular child cursor. 298918334Speter * 299018334Speter * A value of this enumeration type should be returned by each 299118334Speter * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 299218334Speter */ 299318334Speterenum CXChildVisitResult { 299418334Speter /** 299518334Speter * \brief Terminates the cursor traversal. 299618334Speter */ 299718334Speter CXChildVisit_Break, 299818334Speter /** 299918334Speter * \brief Continues the cursor traversal with the next sibling of 300018334Speter * the cursor just visited, without visiting its children. 300118334Speter */ 300218334Speter CXChildVisit_Continue, 300318334Speter /** 300418334Speter * \brief Recursively traverse the children of this cursor, using 300518334Speter * the same visitor and client data. 300618334Speter */ 300718334Speter CXChildVisit_Recurse 300818334Speter}; 300918334Speter 301018334Speter/** 301118334Speter * \brief Visitor invoked for each cursor found by a traversal. 301218334Speter * 301318334Speter * This visitor function will be invoked for each cursor found by 301418334Speter * clang_visitCursorChildren(). Its first argument is the cursor being 301518334Speter * visited, its second argument is the parent visitor for that cursor, 301618334Speter * and its third argument is the client data provided to 301718334Speter * clang_visitCursorChildren(). 301818334Speter * 301918334Speter * The visitor should return one of the \c CXChildVisitResult values 302018334Speter * to direct clang_visitCursorChildren(). 302118334Speter */ 302218334Spetertypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 302318334Speter CXCursor parent, 302418334Speter CXClientData client_data); 3025 3026/** 3027 * \brief Visit the children of a particular cursor. 3028 * 3029 * This function visits all the direct children of the given cursor, 3030 * invoking the given \p visitor function with the cursors of each 3031 * visited child. The traversal may be recursive, if the visitor returns 3032 * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 3033 * the visitor returns \c CXChildVisit_Break. 3034 * 3035 * \param parent the cursor whose child may be visited. All kinds of 3036 * cursors can be visited, including invalid cursors (which, by 3037 * definition, have no children). 3038 * 3039 * \param visitor the visitor function that will be invoked for each 3040 * child of \p parent. 3041 * 3042 * \param client_data pointer data supplied by the client, which will 3043 * be passed to the visitor each time it is invoked. 3044 * 3045 * \returns a non-zero value if the traversal was terminated 3046 * prematurely by the visitor returning \c CXChildVisit_Break. 3047 */ 3048CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 3049 CXCursorVisitor visitor, 3050 CXClientData client_data); 3051#ifdef __has_feature 3052# if __has_feature(blocks) 3053/** 3054 * \brief Visitor invoked for each cursor found by a traversal. 3055 * 3056 * This visitor block will be invoked for each cursor found by 3057 * clang_visitChildrenWithBlock(). Its first argument is the cursor being 3058 * visited, its second argument is the parent visitor for that cursor. 3059 * 3060 * The visitor should return one of the \c CXChildVisitResult values 3061 * to direct clang_visitChildrenWithBlock(). 3062 */ 3063typedef enum CXChildVisitResult 3064 (^CXCursorVisitorBlock)(CXCursor cursor, CXCursor parent); 3065 3066/** 3067 * Visits the children of a cursor using the specified block. Behaves 3068 * identically to clang_visitChildren() in all other respects. 3069 */ 3070unsigned clang_visitChildrenWithBlock(CXCursor parent, 3071 CXCursorVisitorBlock block); 3072# endif 3073#endif 3074 3075/** 3076 * @} 3077 */ 3078 3079/** 3080 * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST 3081 * 3082 * These routines provide the ability to determine references within and 3083 * across translation units, by providing the names of the entities referenced 3084 * by cursors, follow reference cursors to the declarations they reference, 3085 * and associate declarations with their definitions. 3086 * 3087 * @{ 3088 */ 3089 3090/** 3091 * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced 3092 * by the given cursor. 3093 * 3094 * A Unified Symbol Resolution (USR) is a string that identifies a particular 3095 * entity (function, class, variable, etc.) within a program. USRs can be 3096 * compared across translation units to determine, e.g., when references in 3097 * one translation refer to an entity defined in another translation unit. 3098 */ 3099CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 3100 3101/** 3102 * \brief Construct a USR for a specified Objective-C class. 3103 */ 3104CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass(const char *class_name); 3105 3106/** 3107 * \brief Construct a USR for a specified Objective-C category. 3108 */ 3109CINDEX_LINKAGE CXString 3110 clang_constructUSR_ObjCCategory(const char *class_name, 3111 const char *category_name); 3112 3113/** 3114 * \brief Construct a USR for a specified Objective-C protocol. 3115 */ 3116CINDEX_LINKAGE CXString 3117 clang_constructUSR_ObjCProtocol(const char *protocol_name); 3118 3119 3120/** 3121 * \brief Construct a USR for a specified Objective-C instance variable and 3122 * the USR for its containing class. 3123 */ 3124CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar(const char *name, 3125 CXString classUSR); 3126 3127/** 3128 * \brief Construct a USR for a specified Objective-C method and 3129 * the USR for its containing class. 3130 */ 3131CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod(const char *name, 3132 unsigned isInstanceMethod, 3133 CXString classUSR); 3134 3135/** 3136 * \brief Construct a USR for a specified Objective-C property and the USR 3137 * for its containing class. 3138 */ 3139CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty(const char *property, 3140 CXString classUSR); 3141 3142/** 3143 * \brief Retrieve a name for the entity referenced by this cursor. 3144 */ 3145CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 3146 3147/** 3148 * \brief Retrieve a range for a piece that forms the cursors spelling name. 3149 * Most of the times there is only one range for the complete spelling but for 3150 * objc methods and objc message expressions, there are multiple pieces for each 3151 * selector identifier. 3152 * 3153 * \param pieceIndex the index of the spelling name piece. If this is greater 3154 * than the actual number of pieces, it will return a NULL (invalid) range. 3155 * 3156 * \param options Reserved. 3157 */ 3158CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange(CXCursor, 3159 unsigned pieceIndex, 3160 unsigned options); 3161 3162/** 3163 * \brief Retrieve the display name for the entity referenced by this cursor. 3164 * 3165 * The display name contains extra information that helps identify the cursor, 3166 * such as the parameters of a function or template or the arguments of a 3167 * class template specialization. 3168 */ 3169CINDEX_LINKAGE CXString clang_getCursorDisplayName(CXCursor); 3170 3171/** \brief For a cursor that is a reference, retrieve a cursor representing the 3172 * entity that it references. 3173 * 3174 * Reference cursors refer to other entities in the AST. For example, an 3175 * Objective-C superclass reference cursor refers to an Objective-C class. 3176 * This function produces the cursor for the Objective-C class from the 3177 * cursor for the superclass reference. If the input cursor is a declaration or 3178 * definition, it returns that declaration or definition unchanged. 3179 * Otherwise, returns the NULL cursor. 3180 */ 3181CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 3182 3183/** 3184 * \brief For a cursor that is either a reference to or a declaration 3185 * of some entity, retrieve a cursor that describes the definition of 3186 * that entity. 3187 * 3188 * Some entities can be declared multiple times within a translation 3189 * unit, but only one of those declarations can also be a 3190 * definition. For example, given: 3191 * 3192 * \code 3193 * int f(int, int); 3194 * int g(int x, int y) { return f(x, y); } 3195 * int f(int a, int b) { return a + b; } 3196 * int f(int, int); 3197 * \endcode 3198 * 3199 * there are three declarations of the function "f", but only the 3200 * second one is a definition. The clang_getCursorDefinition() 3201 * function will take any cursor pointing to a declaration of "f" 3202 * (the first or fourth lines of the example) or a cursor referenced 3203 * that uses "f" (the call to "f' inside "g") and will return a 3204 * declaration cursor pointing to the definition (the second "f" 3205 * declaration). 3206 * 3207 * If given a cursor for which there is no corresponding definition, 3208 * e.g., because there is no definition of that entity within this 3209 * translation unit, returns a NULL cursor. 3210 */ 3211CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 3212 3213/** 3214 * \brief Determine whether the declaration pointed to by this cursor 3215 * is also a definition of that entity. 3216 */ 3217CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 3218 3219/** 3220 * \brief Retrieve the canonical cursor corresponding to the given cursor. 3221 * 3222 * In the C family of languages, many kinds of entities can be declared several 3223 * times within a single translation unit. For example, a structure type can 3224 * be forward-declared (possibly multiple times) and later defined: 3225 * 3226 * \code 3227 * struct X; 3228 * struct X; 3229 * struct X { 3230 * int member; 3231 * }; 3232 * \endcode 3233 * 3234 * The declarations and the definition of \c X are represented by three 3235 * different cursors, all of which are declarations of the same underlying 3236 * entity. One of these cursor is considered the "canonical" cursor, which 3237 * is effectively the representative for the underlying entity. One can 3238 * determine if two cursors are declarations of the same underlying entity by 3239 * comparing their canonical cursors. 3240 * 3241 * \returns The canonical cursor for the entity referred to by the given cursor. 3242 */ 3243CINDEX_LINKAGE CXCursor clang_getCanonicalCursor(CXCursor); 3244 3245 3246/** 3247 * \brief If the cursor points to a selector identifier in a objc method or 3248 * message expression, this returns the selector index. 3249 * 3250 * After getting a cursor with #clang_getCursor, this can be called to 3251 * determine if the location points to a selector identifier. 3252 * 3253 * \returns The selector index if the cursor is an objc method or message 3254 * expression and the cursor is pointing to a selector identifier, or -1 3255 * otherwise. 3256 */ 3257CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex(CXCursor); 3258 3259/** 3260 * \brief Given a cursor pointing to a C++ method call or an ObjC message, 3261 * returns non-zero if the method/message is "dynamic", meaning: 3262 * 3263 * For a C++ method: the call is virtual. 3264 * For an ObjC message: the receiver is an object instance, not 'super' or a 3265 * specific class. 3266 * 3267 * If the method/message is "static" or the cursor does not point to a 3268 * method/message, it will return zero. 3269 */ 3270CINDEX_LINKAGE int clang_Cursor_isDynamicCall(CXCursor C); 3271 3272/** 3273 * \brief Given a cursor pointing to an ObjC message, returns the CXType of the 3274 * receiver. 3275 */ 3276CINDEX_LINKAGE CXType clang_Cursor_getReceiverType(CXCursor C); 3277 3278/** 3279 * \brief Given a cursor that represents a declaration, return the associated 3280 * comment's source range. The range may include multiple consecutive comments 3281 * with whitespace in between. 3282 */ 3283CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange(CXCursor C); 3284 3285/** 3286 * \brief Given a cursor that represents a declaration, return the associated 3287 * comment text, including comment markers. 3288 */ 3289CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText(CXCursor C); 3290 3291/** 3292 * \brief Given a cursor that represents a documentable entity (e.g., 3293 * declaration), return the associated \\brief paragraph; otherwise return the 3294 * first paragraph. 3295 */ 3296CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText(CXCursor C); 3297 3298/** 3299 * \brief Given a cursor that represents a documentable entity (e.g., 3300 * declaration), return the associated parsed comment as a 3301 * \c CXComment_FullComment AST node. 3302 */ 3303CINDEX_LINKAGE CXComment clang_Cursor_getParsedComment(CXCursor C); 3304 3305/** 3306 * @} 3307 */ 3308 3309/** 3310 * \defgroup CINDEX_MODULE Module introspection 3311 * 3312 * The functions in this group provide access to information about modules. 3313 * 3314 * @{ 3315 */ 3316 3317typedef void *CXModule; 3318 3319/** 3320 * \brief Given a CXCursor_ModuleImportDecl cursor, return the associated module. 3321 */ 3322CINDEX_LINKAGE CXModule clang_Cursor_getModule(CXCursor C); 3323 3324/** 3325 * \param Module a module object. 3326 * 3327 * \returns the parent of a sub-module or NULL if the given module is top-level, 3328 * e.g. for 'std.vector' it will return the 'std' module. 3329 */ 3330CINDEX_LINKAGE CXModule clang_Module_getParent(CXModule Module); 3331 3332/** 3333 * \param Module a module object. 3334 * 3335 * \returns the name of the module, e.g. for the 'std.vector' sub-module it 3336 * will return "vector". 3337 */ 3338CINDEX_LINKAGE CXString clang_Module_getName(CXModule Module); 3339 3340/** 3341 * \param Module a module object. 3342 * 3343 * \returns the full name of the module, e.g. "std.vector". 3344 */ 3345CINDEX_LINKAGE CXString clang_Module_getFullName(CXModule Module); 3346 3347/** 3348 * \param Module a module object. 3349 * 3350 * \returns the number of top level headers associated with this module. 3351 */ 3352CINDEX_LINKAGE unsigned clang_Module_getNumTopLevelHeaders(CXTranslationUnit, 3353 CXModule Module); 3354 3355/** 3356 * \param Module a module object. 3357 * 3358 * \param Index top level header index (zero-based). 3359 * 3360 * \returns the specified top level header associated with the module. 3361 */ 3362CINDEX_LINKAGE 3363CXFile clang_Module_getTopLevelHeader(CXTranslationUnit, 3364 CXModule Module, unsigned Index); 3365 3366/** 3367 * @} 3368 */ 3369 3370/** 3371 * \defgroup CINDEX_COMMENT Comment AST introspection 3372 * 3373 * The routines in this group provide access to information in the 3374 * documentation comment ASTs. 3375 * 3376 * @{ 3377 */ 3378 3379/** 3380 * \brief Describes the type of the comment AST node (\c CXComment). A comment 3381 * node can be considered block content (e. g., paragraph), inline content 3382 * (plain text) or neither (the root AST node). 3383 */ 3384enum CXCommentKind { 3385 /** 3386 * \brief Null comment. No AST node is constructed at the requested location 3387 * because there is no text or a syntax error. 3388 */ 3389 CXComment_Null = 0, 3390 3391 /** 3392 * \brief Plain text. Inline content. 3393 */ 3394 CXComment_Text = 1, 3395 3396 /** 3397 * \brief A command with word-like arguments that is considered inline content. 3398 * 3399 * For example: \\c command. 3400 */ 3401 CXComment_InlineCommand = 2, 3402 3403 /** 3404 * \brief HTML start tag with attributes (name-value pairs). Considered 3405 * inline content. 3406 * 3407 * For example: 3408 * \verbatim 3409 * <br> <br /> <a href="http://example.org/"> 3410 * \endverbatim 3411 */ 3412 CXComment_HTMLStartTag = 3, 3413 3414 /** 3415 * \brief HTML end tag. Considered inline content. 3416 * 3417 * For example: 3418 * \verbatim 3419 * </a> 3420 * \endverbatim 3421 */ 3422 CXComment_HTMLEndTag = 4, 3423 3424 /** 3425 * \brief A paragraph, contains inline comment. The paragraph itself is 3426 * block content. 3427 */ 3428 CXComment_Paragraph = 5, 3429 3430 /** 3431 * \brief A command that has zero or more word-like arguments (number of 3432 * word-like arguments depends on command name) and a paragraph as an 3433 * argument. Block command is block content. 3434 * 3435 * Paragraph argument is also a child of the block command. 3436 * 3437 * For example: \\brief has 0 word-like arguments and a paragraph argument. 3438 * 3439 * AST nodes of special kinds that parser knows about (e. g., \\param 3440 * command) have their own node kinds. 3441 */ 3442 CXComment_BlockCommand = 6, 3443 3444 /** 3445 * \brief A \\param or \\arg command that describes the function parameter 3446 * (name, passing direction, description). 3447 * 3448 * For example: \\param [in] ParamName description. 3449 */ 3450 CXComment_ParamCommand = 7, 3451 3452 /** 3453 * \brief A \\tparam command that describes a template parameter (name and 3454 * description). 3455 * 3456 * For example: \\tparam T description. 3457 */ 3458 CXComment_TParamCommand = 8, 3459 3460 /** 3461 * \brief A verbatim block command (e. g., preformatted code). Verbatim 3462 * block has an opening and a closing command and contains multiple lines of 3463 * text (\c CXComment_VerbatimBlockLine child nodes). 3464 * 3465 * For example: 3466 * \\verbatim 3467 * aaa 3468 * \\endverbatim 3469 */ 3470 CXComment_VerbatimBlockCommand = 9, 3471 3472 /** 3473 * \brief A line of text that is contained within a 3474 * CXComment_VerbatimBlockCommand node. 3475 */ 3476 CXComment_VerbatimBlockLine = 10, 3477 3478 /** 3479 * \brief A verbatim line command. Verbatim line has an opening command, 3480 * a single line of text (up to the newline after the opening command) and 3481 * has no closing command. 3482 */ 3483 CXComment_VerbatimLine = 11, 3484 3485 /** 3486 * \brief A full comment attached to a declaration, contains block content. 3487 */ 3488 CXComment_FullComment = 12 3489}; 3490 3491/** 3492 * \brief The most appropriate rendering mode for an inline command, chosen on 3493 * command semantics in Doxygen. 3494 */ 3495enum CXCommentInlineCommandRenderKind { 3496 /** 3497 * \brief Command argument should be rendered in a normal font. 3498 */ 3499 CXCommentInlineCommandRenderKind_Normal, 3500 3501 /** 3502 * \brief Command argument should be rendered in a bold font. 3503 */ 3504 CXCommentInlineCommandRenderKind_Bold, 3505 3506 /** 3507 * \brief Command argument should be rendered in a monospaced font. 3508 */ 3509 CXCommentInlineCommandRenderKind_Monospaced, 3510 3511 /** 3512 * \brief Command argument should be rendered emphasized (typically italic 3513 * font). 3514 */ 3515 CXCommentInlineCommandRenderKind_Emphasized 3516}; 3517 3518/** 3519 * \brief Describes parameter passing direction for \\param or \\arg command. 3520 */ 3521enum CXCommentParamPassDirection { 3522 /** 3523 * \brief The parameter is an input parameter. 3524 */ 3525 CXCommentParamPassDirection_In, 3526 3527 /** 3528 * \brief The parameter is an output parameter. 3529 */ 3530 CXCommentParamPassDirection_Out, 3531 3532 /** 3533 * \brief The parameter is an input and output parameter. 3534 */ 3535 CXCommentParamPassDirection_InOut 3536}; 3537 3538/** 3539 * \param Comment AST node of any kind. 3540 * 3541 * \returns the type of the AST node. 3542 */ 3543CINDEX_LINKAGE enum CXCommentKind clang_Comment_getKind(CXComment Comment); 3544 3545/** 3546 * \param Comment AST node of any kind. 3547 * 3548 * \returns number of children of the AST node. 3549 */ 3550CINDEX_LINKAGE unsigned clang_Comment_getNumChildren(CXComment Comment); 3551 3552/** 3553 * \param Comment AST node of any kind. 3554 * 3555 * \param ChildIdx child index (zero-based). 3556 * 3557 * \returns the specified child of the AST node. 3558 */ 3559CINDEX_LINKAGE 3560CXComment clang_Comment_getChild(CXComment Comment, unsigned ChildIdx); 3561 3562/** 3563 * \brief A \c CXComment_Paragraph node is considered whitespace if it contains 3564 * only \c CXComment_Text nodes that are empty or whitespace. 3565 * 3566 * Other AST nodes (except \c CXComment_Paragraph and \c CXComment_Text) are 3567 * never considered whitespace. 3568 * 3569 * \returns non-zero if \c Comment is whitespace. 3570 */ 3571CINDEX_LINKAGE unsigned clang_Comment_isWhitespace(CXComment Comment); 3572 3573/** 3574 * \returns non-zero if \c Comment is inline content and has a newline 3575 * immediately following it in the comment text. Newlines between paragraphs 3576 * do not count. 3577 */ 3578CINDEX_LINKAGE 3579unsigned clang_InlineContentComment_hasTrailingNewline(CXComment Comment); 3580 3581/** 3582 * \param Comment a \c CXComment_Text AST node. 3583 * 3584 * \returns text contained in the AST node. 3585 */ 3586CINDEX_LINKAGE CXString clang_TextComment_getText(CXComment Comment); 3587 3588/** 3589 * \param Comment a \c CXComment_InlineCommand AST node. 3590 * 3591 * \returns name of the inline command. 3592 */ 3593CINDEX_LINKAGE 3594CXString clang_InlineCommandComment_getCommandName(CXComment Comment); 3595 3596/** 3597 * \param Comment a \c CXComment_InlineCommand AST node. 3598 * 3599 * \returns the most appropriate rendering mode, chosen on command 3600 * semantics in Doxygen. 3601 */ 3602CINDEX_LINKAGE enum CXCommentInlineCommandRenderKind 3603clang_InlineCommandComment_getRenderKind(CXComment Comment); 3604 3605/** 3606 * \param Comment a \c CXComment_InlineCommand AST node. 3607 * 3608 * \returns number of command arguments. 3609 */ 3610CINDEX_LINKAGE 3611unsigned clang_InlineCommandComment_getNumArgs(CXComment Comment); 3612 3613/** 3614 * \param Comment a \c CXComment_InlineCommand AST node. 3615 * 3616 * \param ArgIdx argument index (zero-based). 3617 * 3618 * \returns text of the specified argument. 3619 */ 3620CINDEX_LINKAGE 3621CXString clang_InlineCommandComment_getArgText(CXComment Comment, 3622 unsigned ArgIdx); 3623 3624/** 3625 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 3626 * node. 3627 * 3628 * \returns HTML tag name. 3629 */ 3630CINDEX_LINKAGE CXString clang_HTMLTagComment_getTagName(CXComment Comment); 3631 3632/** 3633 * \param Comment a \c CXComment_HTMLStartTag AST node. 3634 * 3635 * \returns non-zero if tag is self-closing (for example, <br />). 3636 */ 3637CINDEX_LINKAGE 3638unsigned clang_HTMLStartTagComment_isSelfClosing(CXComment Comment); 3639 3640/** 3641 * \param Comment a \c CXComment_HTMLStartTag AST node. 3642 * 3643 * \returns number of attributes (name-value pairs) attached to the start tag. 3644 */ 3645CINDEX_LINKAGE unsigned clang_HTMLStartTag_getNumAttrs(CXComment Comment); 3646 3647/** 3648 * \param Comment a \c CXComment_HTMLStartTag AST node. 3649 * 3650 * \param AttrIdx attribute index (zero-based). 3651 * 3652 * \returns name of the specified attribute. 3653 */ 3654CINDEX_LINKAGE 3655CXString clang_HTMLStartTag_getAttrName(CXComment Comment, unsigned AttrIdx); 3656 3657/** 3658 * \param Comment a \c CXComment_HTMLStartTag AST node. 3659 * 3660 * \param AttrIdx attribute index (zero-based). 3661 * 3662 * \returns value of the specified attribute. 3663 */ 3664CINDEX_LINKAGE 3665CXString clang_HTMLStartTag_getAttrValue(CXComment Comment, unsigned AttrIdx); 3666 3667/** 3668 * \param Comment a \c CXComment_BlockCommand AST node. 3669 * 3670 * \returns name of the block command. 3671 */ 3672CINDEX_LINKAGE 3673CXString clang_BlockCommandComment_getCommandName(CXComment Comment); 3674 3675/** 3676 * \param Comment a \c CXComment_BlockCommand AST node. 3677 * 3678 * \returns number of word-like arguments. 3679 */ 3680CINDEX_LINKAGE 3681unsigned clang_BlockCommandComment_getNumArgs(CXComment Comment); 3682 3683/** 3684 * \param Comment a \c CXComment_BlockCommand AST node. 3685 * 3686 * \param ArgIdx argument index (zero-based). 3687 * 3688 * \returns text of the specified word-like argument. 3689 */ 3690CINDEX_LINKAGE 3691CXString clang_BlockCommandComment_getArgText(CXComment Comment, 3692 unsigned ArgIdx); 3693 3694/** 3695 * \param Comment a \c CXComment_BlockCommand or 3696 * \c CXComment_VerbatimBlockCommand AST node. 3697 * 3698 * \returns paragraph argument of the block command. 3699 */ 3700CINDEX_LINKAGE 3701CXComment clang_BlockCommandComment_getParagraph(CXComment Comment); 3702 3703/** 3704 * \param Comment a \c CXComment_ParamCommand AST node. 3705 * 3706 * \returns parameter name. 3707 */ 3708CINDEX_LINKAGE 3709CXString clang_ParamCommandComment_getParamName(CXComment Comment); 3710 3711/** 3712 * \param Comment a \c CXComment_ParamCommand AST node. 3713 * 3714 * \returns non-zero if the parameter that this AST node represents was found 3715 * in the function prototype and \c clang_ParamCommandComment_getParamIndex 3716 * function will return a meaningful value. 3717 */ 3718CINDEX_LINKAGE 3719unsigned clang_ParamCommandComment_isParamIndexValid(CXComment Comment); 3720 3721/** 3722 * \param Comment a \c CXComment_ParamCommand AST node. 3723 * 3724 * \returns zero-based parameter index in function prototype. 3725 */ 3726CINDEX_LINKAGE 3727unsigned clang_ParamCommandComment_getParamIndex(CXComment Comment); 3728 3729/** 3730 * \param Comment a \c CXComment_ParamCommand AST node. 3731 * 3732 * \returns non-zero if parameter passing direction was specified explicitly in 3733 * the comment. 3734 */ 3735CINDEX_LINKAGE 3736unsigned clang_ParamCommandComment_isDirectionExplicit(CXComment Comment); 3737 3738/** 3739 * \param Comment a \c CXComment_ParamCommand AST node. 3740 * 3741 * \returns parameter passing direction. 3742 */ 3743CINDEX_LINKAGE 3744enum CXCommentParamPassDirection clang_ParamCommandComment_getDirection( 3745 CXComment Comment); 3746 3747/** 3748 * \param Comment a \c CXComment_TParamCommand AST node. 3749 * 3750 * \returns template parameter name. 3751 */ 3752CINDEX_LINKAGE 3753CXString clang_TParamCommandComment_getParamName(CXComment Comment); 3754 3755/** 3756 * \param Comment a \c CXComment_TParamCommand AST node. 3757 * 3758 * \returns non-zero if the parameter that this AST node represents was found 3759 * in the template parameter list and 3760 * \c clang_TParamCommandComment_getDepth and 3761 * \c clang_TParamCommandComment_getIndex functions will return a meaningful 3762 * value. 3763 */ 3764CINDEX_LINKAGE 3765unsigned clang_TParamCommandComment_isParamPositionValid(CXComment Comment); 3766 3767/** 3768 * \param Comment a \c CXComment_TParamCommand AST node. 3769 * 3770 * \returns zero-based nesting depth of this parameter in the template parameter list. 3771 * 3772 * For example, 3773 * \verbatim 3774 * template<typename C, template<typename T> class TT> 3775 * void test(TT<int> aaa); 3776 * \endverbatim 3777 * for C and TT nesting depth is 0, 3778 * for T nesting depth is 1. 3779 */ 3780CINDEX_LINKAGE 3781unsigned clang_TParamCommandComment_getDepth(CXComment Comment); 3782 3783/** 3784 * \param Comment a \c CXComment_TParamCommand AST node. 3785 * 3786 * \returns zero-based parameter index in the template parameter list at a 3787 * given nesting depth. 3788 * 3789 * For example, 3790 * \verbatim 3791 * template<typename C, template<typename T> class TT> 3792 * void test(TT<int> aaa); 3793 * \endverbatim 3794 * for C and TT nesting depth is 0, so we can ask for index at depth 0: 3795 * at depth 0 C's index is 0, TT's index is 1. 3796 * 3797 * For T nesting depth is 1, so we can ask for index at depth 0 and 1: 3798 * at depth 0 T's index is 1 (same as TT's), 3799 * at depth 1 T's index is 0. 3800 */ 3801CINDEX_LINKAGE 3802unsigned clang_TParamCommandComment_getIndex(CXComment Comment, unsigned Depth); 3803 3804/** 3805 * \param Comment a \c CXComment_VerbatimBlockLine AST node. 3806 * 3807 * \returns text contained in the AST node. 3808 */ 3809CINDEX_LINKAGE 3810CXString clang_VerbatimBlockLineComment_getText(CXComment Comment); 3811 3812/** 3813 * \param Comment a \c CXComment_VerbatimLine AST node. 3814 * 3815 * \returns text contained in the AST node. 3816 */ 3817CINDEX_LINKAGE CXString clang_VerbatimLineComment_getText(CXComment Comment); 3818 3819/** 3820 * \brief Convert an HTML tag AST node to string. 3821 * 3822 * \param Comment a \c CXComment_HTMLStartTag or \c CXComment_HTMLEndTag AST 3823 * node. 3824 * 3825 * \returns string containing an HTML tag. 3826 */ 3827CINDEX_LINKAGE CXString clang_HTMLTagComment_getAsString(CXComment Comment); 3828 3829/** 3830 * \brief Convert a given full parsed comment to an HTML fragment. 3831 * 3832 * Specific details of HTML layout are subject to change. Don't try to parse 3833 * this HTML back into an AST, use other APIs instead. 3834 * 3835 * Currently the following CSS classes are used: 3836 * \li "para-brief" for \\brief paragraph and equivalent commands; 3837 * \li "para-returns" for \\returns paragraph and equivalent commands; 3838 * \li "word-returns" for the "Returns" word in \\returns paragraph. 3839 * 3840 * Function argument documentation is rendered as a \<dl\> list with arguments 3841 * sorted in function prototype order. CSS classes used: 3842 * \li "param-name-index-NUMBER" for parameter name (\<dt\>); 3843 * \li "param-descr-index-NUMBER" for parameter description (\<dd\>); 3844 * \li "param-name-index-invalid" and "param-descr-index-invalid" are used if 3845 * parameter index is invalid. 3846 * 3847 * Template parameter documentation is rendered as a \<dl\> list with 3848 * parameters sorted in template parameter list order. CSS classes used: 3849 * \li "tparam-name-index-NUMBER" for parameter name (\<dt\>); 3850 * \li "tparam-descr-index-NUMBER" for parameter description (\<dd\>); 3851 * \li "tparam-name-index-other" and "tparam-descr-index-other" are used for 3852 * names inside template template parameters; 3853 * \li "tparam-name-index-invalid" and "tparam-descr-index-invalid" are used if 3854 * parameter position is invalid. 3855 * 3856 * \param Comment a \c CXComment_FullComment AST node. 3857 * 3858 * \returns string containing an HTML fragment. 3859 */ 3860CINDEX_LINKAGE CXString clang_FullComment_getAsHTML(CXComment Comment); 3861 3862/** 3863 * \brief Convert a given full parsed comment to an XML document. 3864 * 3865 * A Relax NG schema for the XML can be found in comment-xml-schema.rng file 3866 * inside clang source tree. 3867 * 3868 * \param Comment a \c CXComment_FullComment AST node. 3869 * 3870 * \returns string containing an XML document. 3871 */ 3872CINDEX_LINKAGE CXString clang_FullComment_getAsXML(CXComment Comment); 3873 3874/** 3875 * @} 3876 */ 3877 3878/** 3879 * \defgroup CINDEX_CPP C++ AST introspection 3880 * 3881 * The routines in this group provide access information in the ASTs specific 3882 * to C++ language features. 3883 * 3884 * @{ 3885 */ 3886 3887/** 3888 * \brief Determine if a C++ member function or member function template is 3889 * declared 'static'. 3890 */ 3891CINDEX_LINKAGE unsigned clang_CXXMethod_isStatic(CXCursor C); 3892 3893/** 3894 * \brief Determine if a C++ member function or member function template is 3895 * explicitly declared 'virtual' or if it overrides a virtual method from 3896 * one of the base classes. 3897 */ 3898CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C); 3899 3900/** 3901 * \brief Given a cursor that represents a template, determine 3902 * the cursor kind of the specializations would be generated by instantiating 3903 * the template. 3904 * 3905 * This routine can be used to determine what flavor of function template, 3906 * class template, or class template partial specialization is stored in the 3907 * cursor. For example, it can describe whether a class template cursor is 3908 * declared with "struct", "class" or "union". 3909 * 3910 * \param C The cursor to query. This cursor should represent a template 3911 * declaration. 3912 * 3913 * \returns The cursor kind of the specializations that would be generated 3914 * by instantiating the template \p C. If \p C is not a template, returns 3915 * \c CXCursor_NoDeclFound. 3916 */ 3917CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C); 3918 3919/** 3920 * \brief Given a cursor that may represent a specialization or instantiation 3921 * of a template, retrieve the cursor that represents the template that it 3922 * specializes or from which it was instantiated. 3923 * 3924 * This routine determines the template involved both for explicit 3925 * specializations of templates and for implicit instantiations of the template, 3926 * both of which are referred to as "specializations". For a class template 3927 * specialization (e.g., \c std::vector<bool>), this routine will return 3928 * either the primary template (\c std::vector) or, if the specialization was 3929 * instantiated from a class template partial specialization, the class template 3930 * partial specialization. For a class template partial specialization and a 3931 * function template specialization (including instantiations), this 3932 * this routine will return the specialized template. 3933 * 3934 * For members of a class template (e.g., member functions, member classes, or 3935 * static data members), returns the specialized or instantiated member. 3936 * Although not strictly "templates" in the C++ language, members of class 3937 * templates have the same notions of specializations and instantiations that 3938 * templates do, so this routine treats them similarly. 3939 * 3940 * \param C A cursor that may be a specialization of a template or a member 3941 * of a template. 3942 * 3943 * \returns If the given cursor is a specialization or instantiation of a 3944 * template or a member thereof, the template or member that it specializes or 3945 * from which it was instantiated. Otherwise, returns a NULL cursor. 3946 */ 3947CINDEX_LINKAGE CXCursor clang_getSpecializedCursorTemplate(CXCursor C); 3948 3949/** 3950 * \brief Given a cursor that references something else, return the source range 3951 * covering that reference. 3952 * 3953 * \param C A cursor pointing to a member reference, a declaration reference, or 3954 * an operator call. 3955 * \param NameFlags A bitset with three independent flags: 3956 * CXNameRange_WantQualifier, CXNameRange_WantTemplateArgs, and 3957 * CXNameRange_WantSinglePiece. 3958 * \param PieceIndex For contiguous names or when passing the flag 3959 * CXNameRange_WantSinglePiece, only one piece with index 0 is 3960 * available. When the CXNameRange_WantSinglePiece flag is not passed for a 3961 * non-contiguous names, this index can be used to retrieve the individual 3962 * pieces of the name. See also CXNameRange_WantSinglePiece. 3963 * 3964 * \returns The piece of the name pointed to by the given cursor. If there is no 3965 * name, or if the PieceIndex is out-of-range, a null-cursor will be returned. 3966 */ 3967CINDEX_LINKAGE CXSourceRange clang_getCursorReferenceNameRange(CXCursor C, 3968 unsigned NameFlags, 3969 unsigned PieceIndex); 3970 3971enum CXNameRefFlags { 3972 /** 3973 * \brief Include the nested-name-specifier, e.g. Foo:: in x.Foo::y, in the 3974 * range. 3975 */ 3976 CXNameRange_WantQualifier = 0x1, 3977 3978 /** 3979 * \brief Include the explicit template arguments, e.g. \<int> in x.f<int>, 3980 * in the range. 3981 */ 3982 CXNameRange_WantTemplateArgs = 0x2, 3983 3984 /** 3985 * \brief If the name is non-contiguous, return the full spanning range. 3986 * 3987 * Non-contiguous names occur in Objective-C when a selector with two or more 3988 * parameters is used, or in C++ when using an operator: 3989 * \code 3990 * [object doSomething:here withValue:there]; // ObjC 3991 * return some_vector[1]; // C++ 3992 * \endcode 3993 */ 3994 CXNameRange_WantSinglePiece = 0x4 3995}; 3996 3997/** 3998 * @} 3999 */ 4000 4001/** 4002 * \defgroup CINDEX_LEX Token extraction and manipulation 4003 * 4004 * The routines in this group provide access to the tokens within a 4005 * translation unit, along with a semantic mapping of those tokens to 4006 * their corresponding cursors. 4007 * 4008 * @{ 4009 */ 4010 4011/** 4012 * \brief Describes a kind of token. 4013 */ 4014typedef enum CXTokenKind { 4015 /** 4016 * \brief A token that contains some kind of punctuation. 4017 */ 4018 CXToken_Punctuation, 4019 4020 /** 4021 * \brief A language keyword. 4022 */ 4023 CXToken_Keyword, 4024 4025 /** 4026 * \brief An identifier (that is not a keyword). 4027 */ 4028 CXToken_Identifier, 4029 4030 /** 4031 * \brief A numeric, string, or character literal. 4032 */ 4033 CXToken_Literal, 4034 4035 /** 4036 * \brief A comment. 4037 */ 4038 CXToken_Comment 4039} CXTokenKind; 4040 4041/** 4042 * \brief Describes a single preprocessing token. 4043 */ 4044typedef struct { 4045 unsigned int_data[4]; 4046 void *ptr_data; 4047} CXToken; 4048 4049/** 4050 * \brief Determine the kind of the given token. 4051 */ 4052CINDEX_LINKAGE CXTokenKind clang_getTokenKind(CXToken); 4053 4054/** 4055 * \brief Determine the spelling of the given token. 4056 * 4057 * The spelling of a token is the textual representation of that token, e.g., 4058 * the text of an identifier or keyword. 4059 */ 4060CINDEX_LINKAGE CXString clang_getTokenSpelling(CXTranslationUnit, CXToken); 4061 4062/** 4063 * \brief Retrieve the source location of the given token. 4064 */ 4065CINDEX_LINKAGE CXSourceLocation clang_getTokenLocation(CXTranslationUnit, 4066 CXToken); 4067 4068/** 4069 * \brief Retrieve a source range that covers the given token. 4070 */ 4071CINDEX_LINKAGE CXSourceRange clang_getTokenExtent(CXTranslationUnit, CXToken); 4072 4073/** 4074 * \brief Tokenize the source code described by the given range into raw 4075 * lexical tokens. 4076 * 4077 * \param TU the translation unit whose text is being tokenized. 4078 * 4079 * \param Range the source range in which text should be tokenized. All of the 4080 * tokens produced by tokenization will fall within this source range, 4081 * 4082 * \param Tokens this pointer will be set to point to the array of tokens 4083 * that occur within the given source range. The returned pointer must be 4084 * freed with clang_disposeTokens() before the translation unit is destroyed. 4085 * 4086 * \param NumTokens will be set to the number of tokens in the \c *Tokens 4087 * array. 4088 * 4089 */ 4090CINDEX_LINKAGE void clang_tokenize(CXTranslationUnit TU, CXSourceRange Range, 4091 CXToken **Tokens, unsigned *NumTokens); 4092 4093/** 4094 * \brief Annotate the given set of tokens by providing cursors for each token 4095 * that can be mapped to a specific entity within the abstract syntax tree. 4096 * 4097 * This token-annotation routine is equivalent to invoking 4098 * clang_getCursor() for the source locations of each of the 4099 * tokens. The cursors provided are filtered, so that only those 4100 * cursors that have a direct correspondence to the token are 4101 * accepted. For example, given a function call \c f(x), 4102 * clang_getCursor() would provide the following cursors: 4103 * 4104 * * when the cursor is over the 'f', a DeclRefExpr cursor referring to 'f'. 4105 * * when the cursor is over the '(' or the ')', a CallExpr referring to 'f'. 4106 * * when the cursor is over the 'x', a DeclRefExpr cursor referring to 'x'. 4107 * 4108 * Only the first and last of these cursors will occur within the 4109 * annotate, since the tokens "f" and "x' directly refer to a function 4110 * and a variable, respectively, but the parentheses are just a small 4111 * part of the full syntax of the function call expression, which is 4112 * not provided as an annotation. 4113 * 4114 * \param TU the translation unit that owns the given tokens. 4115 * 4116 * \param Tokens the set of tokens to annotate. 4117 * 4118 * \param NumTokens the number of tokens in \p Tokens. 4119 * 4120 * \param Cursors an array of \p NumTokens cursors, whose contents will be 4121 * replaced with the cursors corresponding to each token. 4122 */ 4123CINDEX_LINKAGE void clang_annotateTokens(CXTranslationUnit TU, 4124 CXToken *Tokens, unsigned NumTokens, 4125 CXCursor *Cursors); 4126 4127/** 4128 * \brief Free the given set of tokens. 4129 */ 4130CINDEX_LINKAGE void clang_disposeTokens(CXTranslationUnit TU, 4131 CXToken *Tokens, unsigned NumTokens); 4132 4133/** 4134 * @} 4135 */ 4136 4137/** 4138 * \defgroup CINDEX_DEBUG Debugging facilities 4139 * 4140 * These routines are used for testing and debugging, only, and should not 4141 * be relied upon. 4142 * 4143 * @{ 4144 */ 4145 4146/* for debug/testing */ 4147CINDEX_LINKAGE CXString clang_getCursorKindSpelling(enum CXCursorKind Kind); 4148CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 4149 const char **startBuf, 4150 const char **endBuf, 4151 unsigned *startLine, 4152 unsigned *startColumn, 4153 unsigned *endLine, 4154 unsigned *endColumn); 4155CINDEX_LINKAGE void clang_enableStackTraces(void); 4156CINDEX_LINKAGE void clang_executeOnThread(void (*fn)(void*), void *user_data, 4157 unsigned stack_size); 4158 4159/** 4160 * @} 4161 */ 4162 4163/** 4164 * \defgroup CINDEX_CODE_COMPLET Code completion 4165 * 4166 * Code completion involves taking an (incomplete) source file, along with 4167 * knowledge of where the user is actively editing that file, and suggesting 4168 * syntactically- and semantically-valid constructs that the user might want to 4169 * use at that particular point in the source code. These data structures and 4170 * routines provide support for code completion. 4171 * 4172 * @{ 4173 */ 4174 4175/** 4176 * \brief A semantic string that describes a code-completion result. 4177 * 4178 * A semantic string that describes the formatting of a code-completion 4179 * result as a single "template" of text that should be inserted into the 4180 * source buffer when a particular code-completion result is selected. 4181 * Each semantic string is made up of some number of "chunks", each of which 4182 * contains some text along with a description of what that text means, e.g., 4183 * the name of the entity being referenced, whether the text chunk is part of 4184 * the template, or whether it is a "placeholder" that the user should replace 4185 * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 4186 * description of the different kinds of chunks. 4187 */ 4188typedef void *CXCompletionString; 4189 4190/** 4191 * \brief A single result of code completion. 4192 */ 4193typedef struct { 4194 /** 4195 * \brief The kind of entity that this completion refers to. 4196 * 4197 * The cursor kind will be a macro, keyword, or a declaration (one of the 4198 * *Decl cursor kinds), describing the entity that the completion is 4199 * referring to. 4200 * 4201 * \todo In the future, we would like to provide a full cursor, to allow 4202 * the client to extract additional information from declaration. 4203 */ 4204 enum CXCursorKind CursorKind; 4205 4206 /** 4207 * \brief The code-completion string that describes how to insert this 4208 * code-completion result into the editing buffer. 4209 */ 4210 CXCompletionString CompletionString; 4211} CXCompletionResult; 4212 4213/** 4214 * \brief Describes a single piece of text within a code-completion string. 4215 * 4216 * Each "chunk" within a code-completion string (\c CXCompletionString) is 4217 * either a piece of text with a specific "kind" that describes how that text 4218 * should be interpreted by the client or is another completion string. 4219 */ 4220enum CXCompletionChunkKind { 4221 /** 4222 * \brief A code-completion string that describes "optional" text that 4223 * could be a part of the template (but is not required). 4224 * 4225 * The Optional chunk is the only kind of chunk that has a code-completion 4226 * string for its representation, which is accessible via 4227 * \c clang_getCompletionChunkCompletionString(). The code-completion string 4228 * describes an additional part of the template that is completely optional. 4229 * For example, optional chunks can be used to describe the placeholders for 4230 * arguments that match up with defaulted function parameters, e.g. given: 4231 * 4232 * \code 4233 * void f(int x, float y = 3.14, double z = 2.71828); 4234 * \endcode 4235 * 4236 * The code-completion string for this function would contain: 4237 * - a TypedText chunk for "f". 4238 * - a LeftParen chunk for "(". 4239 * - a Placeholder chunk for "int x" 4240 * - an Optional chunk containing the remaining defaulted arguments, e.g., 4241 * - a Comma chunk for "," 4242 * - a Placeholder chunk for "float y" 4243 * - an Optional chunk containing the last defaulted argument: 4244 * - a Comma chunk for "," 4245 * - a Placeholder chunk for "double z" 4246 * - a RightParen chunk for ")" 4247 * 4248 * There are many ways to handle Optional chunks. Two simple approaches are: 4249 * - Completely ignore optional chunks, in which case the template for the 4250 * function "f" would only include the first parameter ("int x"). 4251 * - Fully expand all optional chunks, in which case the template for the 4252 * function "f" would have all of the parameters. 4253 */ 4254 CXCompletionChunk_Optional, 4255 /** 4256 * \brief Text that a user would be expected to type to get this 4257 * code-completion result. 4258 * 4259 * There will be exactly one "typed text" chunk in a semantic string, which 4260 * will typically provide the spelling of a keyword or the name of a 4261 * declaration that could be used at the current code point. Clients are 4262 * expected to filter the code-completion results based on the text in this 4263 * chunk. 4264 */ 4265 CXCompletionChunk_TypedText, 4266 /** 4267 * \brief Text that should be inserted as part of a code-completion result. 4268 * 4269 * A "text" chunk represents text that is part of the template to be 4270 * inserted into user code should this particular code-completion result 4271 * be selected. 4272 */ 4273 CXCompletionChunk_Text, 4274 /** 4275 * \brief Placeholder text that should be replaced by the user. 4276 * 4277 * A "placeholder" chunk marks a place where the user should insert text 4278 * into the code-completion template. For example, placeholders might mark 4279 * the function parameters for a function declaration, to indicate that the 4280 * user should provide arguments for each of those parameters. The actual 4281 * text in a placeholder is a suggestion for the text to display before 4282 * the user replaces the placeholder with real code. 4283 */ 4284 CXCompletionChunk_Placeholder, 4285 /** 4286 * \brief Informative text that should be displayed but never inserted as 4287 * part of the template. 4288 * 4289 * An "informative" chunk contains annotations that can be displayed to 4290 * help the user decide whether a particular code-completion result is the 4291 * right option, but which is not part of the actual template to be inserted 4292 * by code completion. 4293 */ 4294 CXCompletionChunk_Informative, 4295 /** 4296 * \brief Text that describes the current parameter when code-completion is 4297 * referring to function call, message send, or template specialization. 4298 * 4299 * A "current parameter" chunk occurs when code-completion is providing 4300 * information about a parameter corresponding to the argument at the 4301 * code-completion point. For example, given a function 4302 * 4303 * \code 4304 * int add(int x, int y); 4305 * \endcode 4306 * 4307 * and the source code \c add(, where the code-completion point is after the 4308 * "(", the code-completion string will contain a "current parameter" chunk 4309 * for "int x", indicating that the current argument will initialize that 4310 * parameter. After typing further, to \c add(17, (where the code-completion 4311 * point is after the ","), the code-completion string will contain a 4312 * "current paremeter" chunk to "int y". 4313 */ 4314 CXCompletionChunk_CurrentParameter, 4315 /** 4316 * \brief A left parenthesis ('('), used to initiate a function call or 4317 * signal the beginning of a function parameter list. 4318 */ 4319 CXCompletionChunk_LeftParen, 4320 /** 4321 * \brief A right parenthesis (')'), used to finish a function call or 4322 * signal the end of a function parameter list. 4323 */ 4324 CXCompletionChunk_RightParen, 4325 /** 4326 * \brief A left bracket ('['). 4327 */ 4328 CXCompletionChunk_LeftBracket, 4329 /** 4330 * \brief A right bracket (']'). 4331 */ 4332 CXCompletionChunk_RightBracket, 4333 /** 4334 * \brief A left brace ('{'). 4335 */ 4336 CXCompletionChunk_LeftBrace, 4337 /** 4338 * \brief A right brace ('}'). 4339 */ 4340 CXCompletionChunk_RightBrace, 4341 /** 4342 * \brief A left angle bracket ('<'). 4343 */ 4344 CXCompletionChunk_LeftAngle, 4345 /** 4346 * \brief A right angle bracket ('>'). 4347 */ 4348 CXCompletionChunk_RightAngle, 4349 /** 4350 * \brief A comma separator (','). 4351 */ 4352 CXCompletionChunk_Comma, 4353 /** 4354 * \brief Text that specifies the result type of a given result. 4355 * 4356 * This special kind of informative chunk is not meant to be inserted into 4357 * the text buffer. Rather, it is meant to illustrate the type that an 4358 * expression using the given completion string would have. 4359 */ 4360 CXCompletionChunk_ResultType, 4361 /** 4362 * \brief A colon (':'). 4363 */ 4364 CXCompletionChunk_Colon, 4365 /** 4366 * \brief A semicolon (';'). 4367 */ 4368 CXCompletionChunk_SemiColon, 4369 /** 4370 * \brief An '=' sign. 4371 */ 4372 CXCompletionChunk_Equal, 4373 /** 4374 * Horizontal space (' '). 4375 */ 4376 CXCompletionChunk_HorizontalSpace, 4377 /** 4378 * Vertical space ('\n'), after which it is generally a good idea to 4379 * perform indentation. 4380 */ 4381 CXCompletionChunk_VerticalSpace 4382}; 4383 4384/** 4385 * \brief Determine the kind of a particular chunk within a completion string. 4386 * 4387 * \param completion_string the completion string to query. 4388 * 4389 * \param chunk_number the 0-based index of the chunk in the completion string. 4390 * 4391 * \returns the kind of the chunk at the index \c chunk_number. 4392 */ 4393CINDEX_LINKAGE enum CXCompletionChunkKind 4394clang_getCompletionChunkKind(CXCompletionString completion_string, 4395 unsigned chunk_number); 4396 4397/** 4398 * \brief Retrieve the text associated with a particular chunk within a 4399 * completion string. 4400 * 4401 * \param completion_string the completion string to query. 4402 * 4403 * \param chunk_number the 0-based index of the chunk in the completion string. 4404 * 4405 * \returns the text associated with the chunk at index \c chunk_number. 4406 */ 4407CINDEX_LINKAGE CXString 4408clang_getCompletionChunkText(CXCompletionString completion_string, 4409 unsigned chunk_number); 4410 4411/** 4412 * \brief Retrieve the completion string associated with a particular chunk 4413 * within a completion string. 4414 * 4415 * \param completion_string the completion string to query. 4416 * 4417 * \param chunk_number the 0-based index of the chunk in the completion string. 4418 * 4419 * \returns the completion string associated with the chunk at index 4420 * \c chunk_number. 4421 */ 4422CINDEX_LINKAGE CXCompletionString 4423clang_getCompletionChunkCompletionString(CXCompletionString completion_string, 4424 unsigned chunk_number); 4425 4426/** 4427 * \brief Retrieve the number of chunks in the given code-completion string. 4428 */ 4429CINDEX_LINKAGE unsigned 4430clang_getNumCompletionChunks(CXCompletionString completion_string); 4431 4432/** 4433 * \brief Determine the priority of this code completion. 4434 * 4435 * The priority of a code completion indicates how likely it is that this 4436 * particular completion is the completion that the user will select. The 4437 * priority is selected by various internal heuristics. 4438 * 4439 * \param completion_string The completion string to query. 4440 * 4441 * \returns The priority of this completion string. Smaller values indicate 4442 * higher-priority (more likely) completions. 4443 */ 4444CINDEX_LINKAGE unsigned 4445clang_getCompletionPriority(CXCompletionString completion_string); 4446 4447/** 4448 * \brief Determine the availability of the entity that this code-completion 4449 * string refers to. 4450 * 4451 * \param completion_string The completion string to query. 4452 * 4453 * \returns The availability of the completion string. 4454 */ 4455CINDEX_LINKAGE enum CXAvailabilityKind 4456clang_getCompletionAvailability(CXCompletionString completion_string); 4457 4458/** 4459 * \brief Retrieve the number of annotations associated with the given 4460 * completion string. 4461 * 4462 * \param completion_string the completion string to query. 4463 * 4464 * \returns the number of annotations associated with the given completion 4465 * string. 4466 */ 4467CINDEX_LINKAGE unsigned 4468clang_getCompletionNumAnnotations(CXCompletionString completion_string); 4469 4470/** 4471 * \brief Retrieve the annotation associated with the given completion string. 4472 * 4473 * \param completion_string the completion string to query. 4474 * 4475 * \param annotation_number the 0-based index of the annotation of the 4476 * completion string. 4477 * 4478 * \returns annotation string associated with the completion at index 4479 * \c annotation_number, or a NULL string if that annotation is not available. 4480 */ 4481CINDEX_LINKAGE CXString 4482clang_getCompletionAnnotation(CXCompletionString completion_string, 4483 unsigned annotation_number); 4484 4485/** 4486 * \brief Retrieve the parent context of the given completion string. 4487 * 4488 * The parent context of a completion string is the semantic parent of 4489 * the declaration (if any) that the code completion represents. For example, 4490 * a code completion for an Objective-C method would have the method's class 4491 * or protocol as its context. 4492 * 4493 * \param completion_string The code completion string whose parent is 4494 * being queried. 4495 * 4496 * \param kind DEPRECATED: always set to CXCursor_NotImplemented if non-NULL. 4497 * 4498 * \returns The name of the completion parent, e.g., "NSObject" if 4499 * the completion string represents a method in the NSObject class. 4500 */ 4501CINDEX_LINKAGE CXString 4502clang_getCompletionParent(CXCompletionString completion_string, 4503 enum CXCursorKind *kind); 4504 4505/** 4506 * \brief Retrieve the brief documentation comment attached to the declaration 4507 * that corresponds to the given completion string. 4508 */ 4509CINDEX_LINKAGE CXString 4510clang_getCompletionBriefComment(CXCompletionString completion_string); 4511 4512/** 4513 * \brief Retrieve a completion string for an arbitrary declaration or macro 4514 * definition cursor. 4515 * 4516 * \param cursor The cursor to query. 4517 * 4518 * \returns A non-context-sensitive completion string for declaration and macro 4519 * definition cursors, or NULL for other kinds of cursors. 4520 */ 4521CINDEX_LINKAGE CXCompletionString 4522clang_getCursorCompletionString(CXCursor cursor); 4523 4524/** 4525 * \brief Contains the results of code-completion. 4526 * 4527 * This data structure contains the results of code completion, as 4528 * produced by \c clang_codeCompleteAt(). Its contents must be freed by 4529 * \c clang_disposeCodeCompleteResults. 4530 */ 4531typedef struct { 4532 /** 4533 * \brief The code-completion results. 4534 */ 4535 CXCompletionResult *Results; 4536 4537 /** 4538 * \brief The number of code-completion results stored in the 4539 * \c Results array. 4540 */ 4541 unsigned NumResults; 4542} CXCodeCompleteResults; 4543 4544/** 4545 * \brief Flags that can be passed to \c clang_codeCompleteAt() to 4546 * modify its behavior. 4547 * 4548 * The enumerators in this enumeration can be bitwise-OR'd together to 4549 * provide multiple options to \c clang_codeCompleteAt(). 4550 */ 4551enum CXCodeComplete_Flags { 4552 /** 4553 * \brief Whether to include macros within the set of code 4554 * completions returned. 4555 */ 4556 CXCodeComplete_IncludeMacros = 0x01, 4557 4558 /** 4559 * \brief Whether to include code patterns for language constructs 4560 * within the set of code completions, e.g., for loops. 4561 */ 4562 CXCodeComplete_IncludeCodePatterns = 0x02, 4563 4564 /** 4565 * \brief Whether to include brief documentation within the set of code 4566 * completions returned. 4567 */ 4568 CXCodeComplete_IncludeBriefComments = 0x04 4569}; 4570 4571/** 4572 * \brief Bits that represent the context under which completion is occurring. 4573 * 4574 * The enumerators in this enumeration may be bitwise-OR'd together if multiple 4575 * contexts are occurring simultaneously. 4576 */ 4577enum CXCompletionContext { 4578 /** 4579 * \brief The context for completions is unexposed, as only Clang results 4580 * should be included. (This is equivalent to having no context bits set.) 4581 */ 4582 CXCompletionContext_Unexposed = 0, 4583 4584 /** 4585 * \brief Completions for any possible type should be included in the results. 4586 */ 4587 CXCompletionContext_AnyType = 1 << 0, 4588 4589 /** 4590 * \brief Completions for any possible value (variables, function calls, etc.) 4591 * should be included in the results. 4592 */ 4593 CXCompletionContext_AnyValue = 1 << 1, 4594 /** 4595 * \brief Completions for values that resolve to an Objective-C object should 4596 * be included in the results. 4597 */ 4598 CXCompletionContext_ObjCObjectValue = 1 << 2, 4599 /** 4600 * \brief Completions for values that resolve to an Objective-C selector 4601 * should be included in the results. 4602 */ 4603 CXCompletionContext_ObjCSelectorValue = 1 << 3, 4604 /** 4605 * \brief Completions for values that resolve to a C++ class type should be 4606 * included in the results. 4607 */ 4608 CXCompletionContext_CXXClassTypeValue = 1 << 4, 4609 4610 /** 4611 * \brief Completions for fields of the member being accessed using the dot 4612 * operator should be included in the results. 4613 */ 4614 CXCompletionContext_DotMemberAccess = 1 << 5, 4615 /** 4616 * \brief Completions for fields of the member being accessed using the arrow 4617 * operator should be included in the results. 4618 */ 4619 CXCompletionContext_ArrowMemberAccess = 1 << 6, 4620 /** 4621 * \brief Completions for properties of the Objective-C object being accessed 4622 * using the dot operator should be included in the results. 4623 */ 4624 CXCompletionContext_ObjCPropertyAccess = 1 << 7, 4625 4626 /** 4627 * \brief Completions for enum tags should be included in the results. 4628 */ 4629 CXCompletionContext_EnumTag = 1 << 8, 4630 /** 4631 * \brief Completions for union tags should be included in the results. 4632 */ 4633 CXCompletionContext_UnionTag = 1 << 9, 4634 /** 4635 * \brief Completions for struct tags should be included in the results. 4636 */ 4637 CXCompletionContext_StructTag = 1 << 10, 4638 4639 /** 4640 * \brief Completions for C++ class names should be included in the results. 4641 */ 4642 CXCompletionContext_ClassTag = 1 << 11, 4643 /** 4644 * \brief Completions for C++ namespaces and namespace aliases should be 4645 * included in the results. 4646 */ 4647 CXCompletionContext_Namespace = 1 << 12, 4648 /** 4649 * \brief Completions for C++ nested name specifiers should be included in 4650 * the results. 4651 */ 4652 CXCompletionContext_NestedNameSpecifier = 1 << 13, 4653 4654 /** 4655 * \brief Completions for Objective-C interfaces (classes) should be included 4656 * in the results. 4657 */ 4658 CXCompletionContext_ObjCInterface = 1 << 14, 4659 /** 4660 * \brief Completions for Objective-C protocols should be included in 4661 * the results. 4662 */ 4663 CXCompletionContext_ObjCProtocol = 1 << 15, 4664 /** 4665 * \brief Completions for Objective-C categories should be included in 4666 * the results. 4667 */ 4668 CXCompletionContext_ObjCCategory = 1 << 16, 4669 /** 4670 * \brief Completions for Objective-C instance messages should be included 4671 * in the results. 4672 */ 4673 CXCompletionContext_ObjCInstanceMessage = 1 << 17, 4674 /** 4675 * \brief Completions for Objective-C class messages should be included in 4676 * the results. 4677 */ 4678 CXCompletionContext_ObjCClassMessage = 1 << 18, 4679 /** 4680 * \brief Completions for Objective-C selector names should be included in 4681 * the results. 4682 */ 4683 CXCompletionContext_ObjCSelectorName = 1 << 19, 4684 4685 /** 4686 * \brief Completions for preprocessor macro names should be included in 4687 * the results. 4688 */ 4689 CXCompletionContext_MacroName = 1 << 20, 4690 4691 /** 4692 * \brief Natural language completions should be included in the results. 4693 */ 4694 CXCompletionContext_NaturalLanguage = 1 << 21, 4695 4696 /** 4697 * \brief The current context is unknown, so set all contexts. 4698 */ 4699 CXCompletionContext_Unknown = ((1 << 22) - 1) 4700}; 4701 4702/** 4703 * \brief Returns a default set of code-completion options that can be 4704 * passed to\c clang_codeCompleteAt(). 4705 */ 4706CINDEX_LINKAGE unsigned clang_defaultCodeCompleteOptions(void); 4707 4708/** 4709 * \brief Perform code completion at a given location in a translation unit. 4710 * 4711 * This function performs code completion at a particular file, line, and 4712 * column within source code, providing results that suggest potential 4713 * code snippets based on the context of the completion. The basic model 4714 * for code completion is that Clang will parse a complete source file, 4715 * performing syntax checking up to the location where code-completion has 4716 * been requested. At that point, a special code-completion token is passed 4717 * to the parser, which recognizes this token and determines, based on the 4718 * current location in the C/Objective-C/C++ grammar and the state of 4719 * semantic analysis, what completions to provide. These completions are 4720 * returned via a new \c CXCodeCompleteResults structure. 4721 * 4722 * Code completion itself is meant to be triggered by the client when the 4723 * user types punctuation characters or whitespace, at which point the 4724 * code-completion location will coincide with the cursor. For example, if \c p 4725 * is a pointer, code-completion might be triggered after the "-" and then 4726 * after the ">" in \c p->. When the code-completion location is afer the ">", 4727 * the completion results will provide, e.g., the members of the struct that 4728 * "p" points to. The client is responsible for placing the cursor at the 4729 * beginning of the token currently being typed, then filtering the results 4730 * based on the contents of the token. For example, when code-completing for 4731 * the expression \c p->get, the client should provide the location just after 4732 * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 4733 * client can filter the results based on the current token text ("get"), only 4734 * showing those results that start with "get". The intent of this interface 4735 * is to separate the relatively high-latency acquisition of code-completion 4736 * results from the filtering of results on a per-character basis, which must 4737 * have a lower latency. 4738 * 4739 * \param TU The translation unit in which code-completion should 4740 * occur. The source files for this translation unit need not be 4741 * completely up-to-date (and the contents of those source files may 4742 * be overridden via \p unsaved_files). Cursors referring into the 4743 * translation unit may be invalidated by this invocation. 4744 * 4745 * \param complete_filename The name of the source file where code 4746 * completion should be performed. This filename may be any file 4747 * included in the translation unit. 4748 * 4749 * \param complete_line The line at which code-completion should occur. 4750 * 4751 * \param complete_column The column at which code-completion should occur. 4752 * Note that the column should point just after the syntactic construct that 4753 * initiated code completion, and not in the middle of a lexical token. 4754 * 4755 * \param unsaved_files the Tiles that have not yet been saved to disk 4756 * but may be required for parsing or code completion, including the 4757 * contents of those files. The contents and name of these files (as 4758 * specified by CXUnsavedFile) are copied when necessary, so the 4759 * client only needs to guarantee their validity until the call to 4760 * this function returns. 4761 * 4762 * \param num_unsaved_files The number of unsaved file entries in \p 4763 * unsaved_files. 4764 * 4765 * \param options Extra options that control the behavior of code 4766 * completion, expressed as a bitwise OR of the enumerators of the 4767 * CXCodeComplete_Flags enumeration. The 4768 * \c clang_defaultCodeCompleteOptions() function returns a default set 4769 * of code-completion options. 4770 * 4771 * \returns If successful, a new \c CXCodeCompleteResults structure 4772 * containing code-completion results, which should eventually be 4773 * freed with \c clang_disposeCodeCompleteResults(). If code 4774 * completion fails, returns NULL. 4775 */ 4776CINDEX_LINKAGE 4777CXCodeCompleteResults *clang_codeCompleteAt(CXTranslationUnit TU, 4778 const char *complete_filename, 4779 unsigned complete_line, 4780 unsigned complete_column, 4781 struct CXUnsavedFile *unsaved_files, 4782 unsigned num_unsaved_files, 4783 unsigned options); 4784 4785/** 4786 * \brief Sort the code-completion results in case-insensitive alphabetical 4787 * order. 4788 * 4789 * \param Results The set of results to sort. 4790 * \param NumResults The number of results in \p Results. 4791 */ 4792CINDEX_LINKAGE 4793void clang_sortCodeCompletionResults(CXCompletionResult *Results, 4794 unsigned NumResults); 4795 4796/** 4797 * \brief Free the given set of code-completion results. 4798 */ 4799CINDEX_LINKAGE 4800void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 4801 4802/** 4803 * \brief Determine the number of diagnostics produced prior to the 4804 * location where code completion was performed. 4805 */ 4806CINDEX_LINKAGE 4807unsigned clang_codeCompleteGetNumDiagnostics(CXCodeCompleteResults *Results); 4808 4809/** 4810 * \brief Retrieve a diagnostic associated with the given code completion. 4811 * 4812 * \param Results the code completion results to query. 4813 * \param Index the zero-based diagnostic number to retrieve. 4814 * 4815 * \returns the requested diagnostic. This diagnostic must be freed 4816 * via a call to \c clang_disposeDiagnostic(). 4817 */ 4818CINDEX_LINKAGE 4819CXDiagnostic clang_codeCompleteGetDiagnostic(CXCodeCompleteResults *Results, 4820 unsigned Index); 4821 4822/** 4823 * \brief Determines what compeltions are appropriate for the context 4824 * the given code completion. 4825 * 4826 * \param Results the code completion results to query 4827 * 4828 * \returns the kinds of completions that are appropriate for use 4829 * along with the given code completion results. 4830 */ 4831CINDEX_LINKAGE 4832unsigned long long clang_codeCompleteGetContexts( 4833 CXCodeCompleteResults *Results); 4834 4835/** 4836 * \brief Returns the cursor kind for the container for the current code 4837 * completion context. The container is only guaranteed to be set for 4838 * contexts where a container exists (i.e. member accesses or Objective-C 4839 * message sends); if there is not a container, this function will return 4840 * CXCursor_InvalidCode. 4841 * 4842 * \param Results the code completion results to query 4843 * 4844 * \param IsIncomplete on return, this value will be false if Clang has complete 4845 * information about the container. If Clang does not have complete 4846 * information, this value will be true. 4847 * 4848 * \returns the container kind, or CXCursor_InvalidCode if there is not a 4849 * container 4850 */ 4851CINDEX_LINKAGE 4852enum CXCursorKind clang_codeCompleteGetContainerKind( 4853 CXCodeCompleteResults *Results, 4854 unsigned *IsIncomplete); 4855 4856/** 4857 * \brief Returns the USR for the container for the current code completion 4858 * context. If there is not a container for the current context, this 4859 * function will return the empty string. 4860 * 4861 * \param Results the code completion results to query 4862 * 4863 * \returns the USR for the container 4864 */ 4865CINDEX_LINKAGE 4866CXString clang_codeCompleteGetContainerUSR(CXCodeCompleteResults *Results); 4867 4868 4869/** 4870 * \brief Returns the currently-entered selector for an Objective-C message 4871 * send, formatted like "initWithFoo:bar:". Only guaranteed to return a 4872 * non-empty string for CXCompletionContext_ObjCInstanceMessage and 4873 * CXCompletionContext_ObjCClassMessage. 4874 * 4875 * \param Results the code completion results to query 4876 * 4877 * \returns the selector (or partial selector) that has been entered thus far 4878 * for an Objective-C message send. 4879 */ 4880CINDEX_LINKAGE 4881CXString clang_codeCompleteGetObjCSelector(CXCodeCompleteResults *Results); 4882 4883/** 4884 * @} 4885 */ 4886 4887 4888/** 4889 * \defgroup CINDEX_MISC Miscellaneous utility functions 4890 * 4891 * @{ 4892 */ 4893 4894/** 4895 * \brief Return a version string, suitable for showing to a user, but not 4896 * intended to be parsed (the format is not guaranteed to be stable). 4897 */ 4898CINDEX_LINKAGE CXString clang_getClangVersion(void); 4899 4900 4901/** 4902 * \brief Enable/disable crash recovery. 4903 * 4904 * \param isEnabled Flag to indicate if crash recovery is enabled. A non-zero 4905 * value enables crash recovery, while 0 disables it. 4906 */ 4907CINDEX_LINKAGE void clang_toggleCrashRecovery(unsigned isEnabled); 4908 4909 /** 4910 * \brief Visitor invoked for each file in a translation unit 4911 * (used with clang_getInclusions()). 4912 * 4913 * This visitor function will be invoked by clang_getInclusions() for each 4914 * file included (either at the top-level or by \#include directives) within 4915 * a translation unit. The first argument is the file being included, and 4916 * the second and third arguments provide the inclusion stack. The 4917 * array is sorted in order of immediate inclusion. For example, 4918 * the first element refers to the location that included 'included_file'. 4919 */ 4920typedef void (*CXInclusionVisitor)(CXFile included_file, 4921 CXSourceLocation* inclusion_stack, 4922 unsigned include_len, 4923 CXClientData client_data); 4924 4925/** 4926 * \brief Visit the set of preprocessor inclusions in a translation unit. 4927 * The visitor function is called with the provided data for every included 4928 * file. This does not include headers included by the PCH file (unless one 4929 * is inspecting the inclusions in the PCH file itself). 4930 */ 4931CINDEX_LINKAGE void clang_getInclusions(CXTranslationUnit tu, 4932 CXInclusionVisitor visitor, 4933 CXClientData client_data); 4934 4935/** 4936 * @} 4937 */ 4938 4939/** \defgroup CINDEX_REMAPPING Remapping functions 4940 * 4941 * @{ 4942 */ 4943 4944/** 4945 * \brief A remapping of original source files and their translated files. 4946 */ 4947typedef void *CXRemapping; 4948 4949/** 4950 * \brief Retrieve a remapping. 4951 * 4952 * \param path the path that contains metadata about remappings. 4953 * 4954 * \returns the requested remapping. This remapping must be freed 4955 * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. 4956 */ 4957CINDEX_LINKAGE CXRemapping clang_getRemappings(const char *path); 4958 4959/** 4960 * \brief Retrieve a remapping. 4961 * 4962 * \param filePaths pointer to an array of file paths containing remapping info. 4963 * 4964 * \param numFiles number of file paths. 4965 * 4966 * \returns the requested remapping. This remapping must be freed 4967 * via a call to \c clang_remap_dispose(). Can return NULL if an error occurred. 4968 */ 4969CINDEX_LINKAGE 4970CXRemapping clang_getRemappingsFromFileList(const char **filePaths, 4971 unsigned numFiles); 4972 4973/** 4974 * \brief Determine the number of remappings. 4975 */ 4976CINDEX_LINKAGE unsigned clang_remap_getNumFiles(CXRemapping); 4977 4978/** 4979 * \brief Get the original and the associated filename from the remapping. 4980 * 4981 * \param original If non-NULL, will be set to the original filename. 4982 * 4983 * \param transformed If non-NULL, will be set to the filename that the original 4984 * is associated with. 4985 */ 4986CINDEX_LINKAGE void clang_remap_getFilenames(CXRemapping, unsigned index, 4987 CXString *original, CXString *transformed); 4988 4989/** 4990 * \brief Dispose the remapping. 4991 */ 4992CINDEX_LINKAGE void clang_remap_dispose(CXRemapping); 4993 4994/** 4995 * @} 4996 */ 4997 4998/** \defgroup CINDEX_HIGH Higher level API functions 4999 * 5000 * @{ 5001 */ 5002 5003enum CXVisitorResult { 5004 CXVisit_Break, 5005 CXVisit_Continue 5006}; 5007 5008typedef struct { 5009 void *context; 5010 enum CXVisitorResult (*visit)(void *context, CXCursor, CXSourceRange); 5011} CXCursorAndRangeVisitor; 5012 5013typedef enum { 5014 /** 5015 * \brief Function returned successfully. 5016 */ 5017 CXResult_Success = 0, 5018 /** 5019 * \brief One of the parameters was invalid for the function. 5020 */ 5021 CXResult_Invalid = 1, 5022 /** 5023 * \brief The function was terminated by a callback (e.g. it returned 5024 * CXVisit_Break) 5025 */ 5026 CXResult_VisitBreak = 2 5027 5028} CXResult; 5029 5030/** 5031 * \brief Find references of a declaration in a specific file. 5032 * 5033 * \param cursor pointing to a declaration or a reference of one. 5034 * 5035 * \param file to search for references. 5036 * 5037 * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for 5038 * each reference found. 5039 * The CXSourceRange will point inside the file; if the reference is inside 5040 * a macro (and not a macro argument) the CXSourceRange will be invalid. 5041 * 5042 * \returns one of the CXResult enumerators. 5043 */ 5044CINDEX_LINKAGE CXResult clang_findReferencesInFile(CXCursor cursor, CXFile file, 5045 CXCursorAndRangeVisitor visitor); 5046 5047/** 5048 * \brief Find #import/#include directives in a specific file. 5049 * 5050 * \param TU translation unit containing the file to query. 5051 * 5052 * \param file to search for #import/#include directives. 5053 * 5054 * \param visitor callback that will receive pairs of CXCursor/CXSourceRange for 5055 * each directive found. 5056 * 5057 * \returns one of the CXResult enumerators. 5058 */ 5059CINDEX_LINKAGE CXResult clang_findIncludesInFile(CXTranslationUnit TU, 5060 CXFile file, 5061 CXCursorAndRangeVisitor visitor); 5062 5063#ifdef __has_feature 5064# if __has_feature(blocks) 5065 5066typedef enum CXVisitorResult 5067 (^CXCursorAndRangeVisitorBlock)(CXCursor, CXSourceRange); 5068 5069CINDEX_LINKAGE 5070CXResult clang_findReferencesInFileWithBlock(CXCursor, CXFile, 5071 CXCursorAndRangeVisitorBlock); 5072 5073CINDEX_LINKAGE 5074CXResult clang_findIncludesInFileWithBlock(CXTranslationUnit, CXFile, 5075 CXCursorAndRangeVisitorBlock); 5076 5077# endif 5078#endif 5079 5080/** 5081 * \brief The client's data object that is associated with a CXFile. 5082 */ 5083typedef void *CXIdxClientFile; 5084 5085/** 5086 * \brief The client's data object that is associated with a semantic entity. 5087 */ 5088typedef void *CXIdxClientEntity; 5089 5090/** 5091 * \brief The client's data object that is associated with a semantic container 5092 * of entities. 5093 */ 5094typedef void *CXIdxClientContainer; 5095 5096/** 5097 * \brief The client's data object that is associated with an AST file (PCH 5098 * or module). 5099 */ 5100typedef void *CXIdxClientASTFile; 5101 5102/** 5103 * \brief Source location passed to index callbacks. 5104 */ 5105typedef struct { 5106 void *ptr_data[2]; 5107 unsigned int_data; 5108} CXIdxLoc; 5109 5110/** 5111 * \brief Data for ppIncludedFile callback. 5112 */ 5113typedef struct { 5114 /** 5115 * \brief Location of '#' in the \#include/\#import directive. 5116 */ 5117 CXIdxLoc hashLoc; 5118 /** 5119 * \brief Filename as written in the \#include/\#import directive. 5120 */ 5121 const char *filename; 5122 /** 5123 * \brief The actual file that the \#include/\#import directive resolved to. 5124 */ 5125 CXFile file; 5126 int isImport; 5127 int isAngled; 5128 /** 5129 * \brief Non-zero if the directive was automatically turned into a module 5130 * import. 5131 */ 5132 int isModuleImport; 5133} CXIdxIncludedFileInfo; 5134 5135/** 5136 * \brief Data for IndexerCallbacks#importedASTFile. 5137 */ 5138typedef struct { 5139 /** 5140 * \brief Top level AST file containing the imported PCH, module or submodule. 5141 */ 5142 CXFile file; 5143 /** 5144 * \brief The imported module or NULL if the AST file is a PCH. 5145 */ 5146 CXModule module; 5147 /** 5148 * \brief Location where the file is imported. Applicable only for modules. 5149 */ 5150 CXIdxLoc loc; 5151 /** 5152 * \brief Non-zero if an inclusion directive was automatically turned into 5153 * a module import. Applicable only for modules. 5154 */ 5155 int isImplicit; 5156 5157} CXIdxImportedASTFileInfo; 5158 5159typedef enum { 5160 CXIdxEntity_Unexposed = 0, 5161 CXIdxEntity_Typedef = 1, 5162 CXIdxEntity_Function = 2, 5163 CXIdxEntity_Variable = 3, 5164 CXIdxEntity_Field = 4, 5165 CXIdxEntity_EnumConstant = 5, 5166 5167 CXIdxEntity_ObjCClass = 6, 5168 CXIdxEntity_ObjCProtocol = 7, 5169 CXIdxEntity_ObjCCategory = 8, 5170 5171 CXIdxEntity_ObjCInstanceMethod = 9, 5172 CXIdxEntity_ObjCClassMethod = 10, 5173 CXIdxEntity_ObjCProperty = 11, 5174 CXIdxEntity_ObjCIvar = 12, 5175 5176 CXIdxEntity_Enum = 13, 5177 CXIdxEntity_Struct = 14, 5178 CXIdxEntity_Union = 15, 5179 5180 CXIdxEntity_CXXClass = 16, 5181 CXIdxEntity_CXXNamespace = 17, 5182 CXIdxEntity_CXXNamespaceAlias = 18, 5183 CXIdxEntity_CXXStaticVariable = 19, 5184 CXIdxEntity_CXXStaticMethod = 20, 5185 CXIdxEntity_CXXInstanceMethod = 21, 5186 CXIdxEntity_CXXConstructor = 22, 5187 CXIdxEntity_CXXDestructor = 23, 5188 CXIdxEntity_CXXConversionFunction = 24, 5189 CXIdxEntity_CXXTypeAlias = 25, 5190 CXIdxEntity_CXXInterface = 26 5191 5192} CXIdxEntityKind; 5193 5194typedef enum { 5195 CXIdxEntityLang_None = 0, 5196 CXIdxEntityLang_C = 1, 5197 CXIdxEntityLang_ObjC = 2, 5198 CXIdxEntityLang_CXX = 3 5199} CXIdxEntityLanguage; 5200 5201/** 5202 * \brief Extra C++ template information for an entity. This can apply to: 5203 * CXIdxEntity_Function 5204 * CXIdxEntity_CXXClass 5205 * CXIdxEntity_CXXStaticMethod 5206 * CXIdxEntity_CXXInstanceMethod 5207 * CXIdxEntity_CXXConstructor 5208 * CXIdxEntity_CXXConversionFunction 5209 * CXIdxEntity_CXXTypeAlias 5210 */ 5211typedef enum { 5212 CXIdxEntity_NonTemplate = 0, 5213 CXIdxEntity_Template = 1, 5214 CXIdxEntity_TemplatePartialSpecialization = 2, 5215 CXIdxEntity_TemplateSpecialization = 3 5216} CXIdxEntityCXXTemplateKind; 5217 5218typedef enum { 5219 CXIdxAttr_Unexposed = 0, 5220 CXIdxAttr_IBAction = 1, 5221 CXIdxAttr_IBOutlet = 2, 5222 CXIdxAttr_IBOutletCollection = 3 5223} CXIdxAttrKind; 5224 5225typedef struct { 5226 CXIdxAttrKind kind; 5227 CXCursor cursor; 5228 CXIdxLoc loc; 5229} CXIdxAttrInfo; 5230 5231typedef struct { 5232 CXIdxEntityKind kind; 5233 CXIdxEntityCXXTemplateKind templateKind; 5234 CXIdxEntityLanguage lang; 5235 const char *name; 5236 const char *USR; 5237 CXCursor cursor; 5238 const CXIdxAttrInfo *const *attributes; 5239 unsigned numAttributes; 5240} CXIdxEntityInfo; 5241 5242typedef struct { 5243 CXCursor cursor; 5244} CXIdxContainerInfo; 5245 5246typedef struct { 5247 const CXIdxAttrInfo *attrInfo; 5248 const CXIdxEntityInfo *objcClass; 5249 CXCursor classCursor; 5250 CXIdxLoc classLoc; 5251} CXIdxIBOutletCollectionAttrInfo; 5252 5253typedef enum { 5254 CXIdxDeclFlag_Skipped = 0x1 5255} CXIdxDeclInfoFlags; 5256 5257typedef struct { 5258 const CXIdxEntityInfo *entityInfo; 5259 CXCursor cursor; 5260 CXIdxLoc loc; 5261 const CXIdxContainerInfo *semanticContainer; 5262 /** 5263 * \brief Generally same as #semanticContainer but can be different in 5264 * cases like out-of-line C++ member functions. 5265 */ 5266 const CXIdxContainerInfo *lexicalContainer; 5267 int isRedeclaration; 5268 int isDefinition; 5269 int isContainer; 5270 const CXIdxContainerInfo *declAsContainer; 5271 /** 5272 * \brief Whether the declaration exists in code or was created implicitly 5273 * by the compiler, e.g. implicit objc methods for properties. 5274 */ 5275 int isImplicit; 5276 const CXIdxAttrInfo *const *attributes; 5277 unsigned numAttributes; 5278 5279 unsigned flags; 5280 5281} CXIdxDeclInfo; 5282 5283typedef enum { 5284 CXIdxObjCContainer_ForwardRef = 0, 5285 CXIdxObjCContainer_Interface = 1, 5286 CXIdxObjCContainer_Implementation = 2 5287} CXIdxObjCContainerKind; 5288 5289typedef struct { 5290 const CXIdxDeclInfo *declInfo; 5291 CXIdxObjCContainerKind kind; 5292} CXIdxObjCContainerDeclInfo; 5293 5294typedef struct { 5295 const CXIdxEntityInfo *base; 5296 CXCursor cursor; 5297 CXIdxLoc loc; 5298} CXIdxBaseClassInfo; 5299 5300typedef struct { 5301 const CXIdxEntityInfo *protocol; 5302 CXCursor cursor; 5303 CXIdxLoc loc; 5304} CXIdxObjCProtocolRefInfo; 5305 5306typedef struct { 5307 const CXIdxObjCProtocolRefInfo *const *protocols; 5308 unsigned numProtocols; 5309} CXIdxObjCProtocolRefListInfo; 5310 5311typedef struct { 5312 const CXIdxObjCContainerDeclInfo *containerInfo; 5313 const CXIdxBaseClassInfo *superInfo; 5314 const CXIdxObjCProtocolRefListInfo *protocols; 5315} CXIdxObjCInterfaceDeclInfo; 5316 5317typedef struct { 5318 const CXIdxObjCContainerDeclInfo *containerInfo; 5319 const CXIdxEntityInfo *objcClass; 5320 CXCursor classCursor; 5321 CXIdxLoc classLoc; 5322 const CXIdxObjCProtocolRefListInfo *protocols; 5323} CXIdxObjCCategoryDeclInfo; 5324 5325typedef struct { 5326 const CXIdxDeclInfo *declInfo; 5327 const CXIdxEntityInfo *getter; 5328 const CXIdxEntityInfo *setter; 5329} CXIdxObjCPropertyDeclInfo; 5330 5331typedef struct { 5332 const CXIdxDeclInfo *declInfo; 5333 const CXIdxBaseClassInfo *const *bases; 5334 unsigned numBases; 5335} CXIdxCXXClassDeclInfo; 5336 5337/** 5338 * \brief Data for IndexerCallbacks#indexEntityReference. 5339 */ 5340typedef enum { 5341 /** 5342 * \brief The entity is referenced directly in user's code. 5343 */ 5344 CXIdxEntityRef_Direct = 1, 5345 /** 5346 * \brief An implicit reference, e.g. a reference of an ObjC method via the 5347 * dot syntax. 5348 */ 5349 CXIdxEntityRef_Implicit = 2 5350} CXIdxEntityRefKind; 5351 5352/** 5353 * \brief Data for IndexerCallbacks#indexEntityReference. 5354 */ 5355typedef struct { 5356 CXIdxEntityRefKind kind; 5357 /** 5358 * \brief Reference cursor. 5359 */ 5360 CXCursor cursor; 5361 CXIdxLoc loc; 5362 /** 5363 * \brief The entity that gets referenced. 5364 */ 5365 const CXIdxEntityInfo *referencedEntity; 5366 /** 5367 * \brief Immediate "parent" of the reference. For example: 5368 * 5369 * \code 5370 * Foo *var; 5371 * \endcode 5372 * 5373 * The parent of reference of type 'Foo' is the variable 'var'. 5374 * For references inside statement bodies of functions/methods, 5375 * the parentEntity will be the function/method. 5376 */ 5377 const CXIdxEntityInfo *parentEntity; 5378 /** 5379 * \brief Lexical container context of the reference. 5380 */ 5381 const CXIdxContainerInfo *container; 5382} CXIdxEntityRefInfo; 5383 5384/** 5385 * \brief A group of callbacks used by #clang_indexSourceFile and 5386 * #clang_indexTranslationUnit. 5387 */ 5388typedef struct { 5389 /** 5390 * \brief Called periodically to check whether indexing should be aborted. 5391 * Should return 0 to continue, and non-zero to abort. 5392 */ 5393 int (*abortQuery)(CXClientData client_data, void *reserved); 5394 5395 /** 5396 * \brief Called at the end of indexing; passes the complete diagnostic set. 5397 */ 5398 void (*diagnostic)(CXClientData client_data, 5399 CXDiagnosticSet, void *reserved); 5400 5401 CXIdxClientFile (*enteredMainFile)(CXClientData client_data, 5402 CXFile mainFile, void *reserved); 5403 5404 /** 5405 * \brief Called when a file gets \#included/\#imported. 5406 */ 5407 CXIdxClientFile (*ppIncludedFile)(CXClientData client_data, 5408 const CXIdxIncludedFileInfo *); 5409 5410 /** 5411 * \brief Called when a AST file (PCH or module) gets imported. 5412 * 5413 * AST files will not get indexed (there will not be callbacks to index all 5414 * the entities in an AST file). The recommended action is that, if the AST 5415 * file is not already indexed, to initiate a new indexing job specific to 5416 * the AST file. 5417 */ 5418 CXIdxClientASTFile (*importedASTFile)(CXClientData client_data, 5419 const CXIdxImportedASTFileInfo *); 5420 5421 /** 5422 * \brief Called at the beginning of indexing a translation unit. 5423 */ 5424 CXIdxClientContainer (*startedTranslationUnit)(CXClientData client_data, 5425 void *reserved); 5426 5427 void (*indexDeclaration)(CXClientData client_data, 5428 const CXIdxDeclInfo *); 5429 5430 /** 5431 * \brief Called to index a reference of an entity. 5432 */ 5433 void (*indexEntityReference)(CXClientData client_data, 5434 const CXIdxEntityRefInfo *); 5435 5436} IndexerCallbacks; 5437 5438CINDEX_LINKAGE int clang_index_isEntityObjCContainerKind(CXIdxEntityKind); 5439CINDEX_LINKAGE const CXIdxObjCContainerDeclInfo * 5440clang_index_getObjCContainerDeclInfo(const CXIdxDeclInfo *); 5441 5442CINDEX_LINKAGE const CXIdxObjCInterfaceDeclInfo * 5443clang_index_getObjCInterfaceDeclInfo(const CXIdxDeclInfo *); 5444 5445CINDEX_LINKAGE 5446const CXIdxObjCCategoryDeclInfo * 5447clang_index_getObjCCategoryDeclInfo(const CXIdxDeclInfo *); 5448 5449CINDEX_LINKAGE const CXIdxObjCProtocolRefListInfo * 5450clang_index_getObjCProtocolRefListInfo(const CXIdxDeclInfo *); 5451 5452CINDEX_LINKAGE const CXIdxObjCPropertyDeclInfo * 5453clang_index_getObjCPropertyDeclInfo(const CXIdxDeclInfo *); 5454 5455CINDEX_LINKAGE const CXIdxIBOutletCollectionAttrInfo * 5456clang_index_getIBOutletCollectionAttrInfo(const CXIdxAttrInfo *); 5457 5458CINDEX_LINKAGE const CXIdxCXXClassDeclInfo * 5459clang_index_getCXXClassDeclInfo(const CXIdxDeclInfo *); 5460 5461/** 5462 * \brief For retrieving a custom CXIdxClientContainer attached to a 5463 * container. 5464 */ 5465CINDEX_LINKAGE CXIdxClientContainer 5466clang_index_getClientContainer(const CXIdxContainerInfo *); 5467 5468/** 5469 * \brief For setting a custom CXIdxClientContainer attached to a 5470 * container. 5471 */ 5472CINDEX_LINKAGE void 5473clang_index_setClientContainer(const CXIdxContainerInfo *,CXIdxClientContainer); 5474 5475/** 5476 * \brief For retrieving a custom CXIdxClientEntity attached to an entity. 5477 */ 5478CINDEX_LINKAGE CXIdxClientEntity 5479clang_index_getClientEntity(const CXIdxEntityInfo *); 5480 5481/** 5482 * \brief For setting a custom CXIdxClientEntity attached to an entity. 5483 */ 5484CINDEX_LINKAGE void 5485clang_index_setClientEntity(const CXIdxEntityInfo *, CXIdxClientEntity); 5486 5487/** 5488 * \brief An indexing action/session, to be applied to one or multiple 5489 * translation units. 5490 */ 5491typedef void *CXIndexAction; 5492 5493/** 5494 * \brief An indexing action/session, to be applied to one or multiple 5495 * translation units. 5496 * 5497 * \param CIdx The index object with which the index action will be associated. 5498 */ 5499CINDEX_LINKAGE CXIndexAction clang_IndexAction_create(CXIndex CIdx); 5500 5501/** 5502 * \brief Destroy the given index action. 5503 * 5504 * The index action must not be destroyed until all of the translation units 5505 * created within that index action have been destroyed. 5506 */ 5507CINDEX_LINKAGE void clang_IndexAction_dispose(CXIndexAction); 5508 5509typedef enum { 5510 /** 5511 * \brief Used to indicate that no special indexing options are needed. 5512 */ 5513 CXIndexOpt_None = 0x0, 5514 5515 /** 5516 * \brief Used to indicate that IndexerCallbacks#indexEntityReference should 5517 * be invoked for only one reference of an entity per source file that does 5518 * not also include a declaration/definition of the entity. 5519 */ 5520 CXIndexOpt_SuppressRedundantRefs = 0x1, 5521 5522 /** 5523 * \brief Function-local symbols should be indexed. If this is not set 5524 * function-local symbols will be ignored. 5525 */ 5526 CXIndexOpt_IndexFunctionLocalSymbols = 0x2, 5527 5528 /** 5529 * \brief Implicit function/class template instantiations should be indexed. 5530 * If this is not set, implicit instantiations will be ignored. 5531 */ 5532 CXIndexOpt_IndexImplicitTemplateInstantiations = 0x4, 5533 5534 /** 5535 * \brief Suppress all compiler warnings when parsing for indexing. 5536 */ 5537 CXIndexOpt_SuppressWarnings = 0x8, 5538 5539 /** 5540 * \brief Skip a function/method body that was already parsed during an 5541 * indexing session assosiated with a \c CXIndexAction object. 5542 * Bodies in system headers are always skipped. 5543 */ 5544 CXIndexOpt_SkipParsedBodiesInSession = 0x10 5545 5546} CXIndexOptFlags; 5547 5548/** 5549 * \brief Index the given source file and the translation unit corresponding 5550 * to that file via callbacks implemented through #IndexerCallbacks. 5551 * 5552 * \param client_data pointer data supplied by the client, which will 5553 * be passed to the invoked callbacks. 5554 * 5555 * \param index_callbacks Pointer to indexing callbacks that the client 5556 * implements. 5557 * 5558 * \param index_callbacks_size Size of #IndexerCallbacks structure that gets 5559 * passed in index_callbacks. 5560 * 5561 * \param index_options A bitmask of options that affects how indexing is 5562 * performed. This should be a bitwise OR of the CXIndexOpt_XXX flags. 5563 * 5564 * \param out_TU [out] pointer to store a CXTranslationUnit that can be reused 5565 * after indexing is finished. Set to NULL if you do not require it. 5566 * 5567 * \returns If there is a failure from which the there is no recovery, returns 5568 * non-zero, otherwise returns 0. 5569 * 5570 * The rest of the parameters are the same as #clang_parseTranslationUnit. 5571 */ 5572CINDEX_LINKAGE int clang_indexSourceFile(CXIndexAction, 5573 CXClientData client_data, 5574 IndexerCallbacks *index_callbacks, 5575 unsigned index_callbacks_size, 5576 unsigned index_options, 5577 const char *source_filename, 5578 const char * const *command_line_args, 5579 int num_command_line_args, 5580 struct CXUnsavedFile *unsaved_files, 5581 unsigned num_unsaved_files, 5582 CXTranslationUnit *out_TU, 5583 unsigned TU_options); 5584 5585/** 5586 * \brief Index the given translation unit via callbacks implemented through 5587 * #IndexerCallbacks. 5588 * 5589 * The order of callback invocations is not guaranteed to be the same as 5590 * when indexing a source file. The high level order will be: 5591 * 5592 * -Preprocessor callbacks invocations 5593 * -Declaration/reference callbacks invocations 5594 * -Diagnostic callback invocations 5595 * 5596 * The parameters are the same as #clang_indexSourceFile. 5597 * 5598 * \returns If there is a failure from which the there is no recovery, returns 5599 * non-zero, otherwise returns 0. 5600 */ 5601CINDEX_LINKAGE int clang_indexTranslationUnit(CXIndexAction, 5602 CXClientData client_data, 5603 IndexerCallbacks *index_callbacks, 5604 unsigned index_callbacks_size, 5605 unsigned index_options, 5606 CXTranslationUnit); 5607 5608/** 5609 * \brief Retrieve the CXIdxFile, file, line, column, and offset represented by 5610 * the given CXIdxLoc. 5611 * 5612 * If the location refers into a macro expansion, retrieves the 5613 * location of the macro expansion and if it refers into a macro argument 5614 * retrieves the location of the argument. 5615 */ 5616CINDEX_LINKAGE void clang_indexLoc_getFileLocation(CXIdxLoc loc, 5617 CXIdxClientFile *indexFile, 5618 CXFile *file, 5619 unsigned *line, 5620 unsigned *column, 5621 unsigned *offset); 5622 5623/** 5624 * \brief Retrieve the CXSourceLocation represented by the given CXIdxLoc. 5625 */ 5626CINDEX_LINKAGE 5627CXSourceLocation clang_indexLoc_getCXSourceLocation(CXIdxLoc loc); 5628 5629/** 5630 * @} 5631 */ 5632 5633/** 5634 * @} 5635 */ 5636 5637#ifdef __cplusplus 5638} 5639#endif 5640#endif 5641 5642