diff options
Diffstat (limited to 'include/clang-c')
| -rw-r--r-- | include/clang-c/Index.h | 896 |
1 files changed, 694 insertions, 202 deletions
diff --git a/include/clang-c/Index.h b/include/clang-c/Index.h index f11a9eb..ef17ed1 100644 --- a/include/clang-c/Index.h +++ b/include/clang-c/Index.h @@ -34,77 +34,42 @@ extern "C" { #define CINDEX_LINKAGE #endif -/* - Clang indeX abstractions. The backing store for the following API's will be - clangs AST file (currently based on PCH). AST files are created as follows: - - "clang -emit-ast <sourcefile.langsuffix> -o <sourcefile.ast>". - - Naming Conventions: To avoid namespace pollution, data types are prefixed - with "CX" and functions are prefixed with "clang_". -*/ -typedef void *CXIndex; /* An indexing instance. */ +/** \defgroup CINDEX C Interface to Clang + * + * The C Interface to Clang provides a relatively small API that exposes + * facilities for parsing source code into an abstract syntax tree (AST), + * loading already-parsed ASTs, traversing the AST, associating + * physical source locations with elements within the AST, and other + * facilities that support Clang-based development tools. + * + * This C interface to Clang will never provide all of the information + * representation stored in Clang's C++ AST, nor should it: the intent is to + * maintain an API that is relatively stable from one release to the next, + * providing only the basic functionality needed to support development tools. + * + * To avoid namespace pollution, data types are prefixed with "CX" and + * functions are prefixed with "clang_". + * + * @{ + */ + +/** + * \brief An "index" that consists of a set of translation units that would + * typically be linked together into an executable or library. + */ +typedef void *CXIndex; +/** + * \brief A single translation unit, which resides in an index. + */ typedef void *CXTranslationUnit; /* A translation unit instance. */ -typedef void *CXFile; /* A source file */ -typedef void *CXDecl; /* A specific declaration within a translation unit. */ -typedef void *CXStmt; /* A specific statement within a function/method */ - -/* Cursors represent declarations, definitions, and references. */ -enum CXCursorKind { - /* Declarations */ - CXCursor_FirstDecl = 1, - CXCursor_TypedefDecl = 2, - CXCursor_StructDecl = 3, - CXCursor_UnionDecl = 4, - CXCursor_ClassDecl = 5, - CXCursor_EnumDecl = 6, - CXCursor_FieldDecl = 7, - CXCursor_EnumConstantDecl = 8, - CXCursor_FunctionDecl = 9, - CXCursor_VarDecl = 10, - CXCursor_ParmDecl = 11, - CXCursor_ObjCInterfaceDecl = 12, - CXCursor_ObjCCategoryDecl = 13, - CXCursor_ObjCProtocolDecl = 14, - CXCursor_ObjCPropertyDecl = 15, - CXCursor_ObjCIvarDecl = 16, - CXCursor_ObjCInstanceMethodDecl = 17, - CXCursor_ObjCClassMethodDecl = 18, - CXCursor_LastDecl = 18, - - /* Definitions */ - CXCursor_FirstDefn = 32, - CXCursor_FunctionDefn = 32, - CXCursor_ObjCClassDefn = 33, - CXCursor_ObjCCategoryDefn = 34, - CXCursor_ObjCInstanceMethodDefn = 35, - CXCursor_ObjCClassMethodDefn = 36, - CXCursor_LastDefn = 36, - - /* References */ - CXCursor_FirstRef = 40, /* Decl references */ - CXCursor_ObjCSuperClassRef = 40, - CXCursor_ObjCProtocolRef = 41, - CXCursor_ObjCClassRef = 42, - - CXCursor_ObjCSelectorRef = 43, /* Expression references */ - CXCursor_ObjCIvarRef = 44, - CXCursor_VarRef = 45, - CXCursor_FunctionRef = 46, - CXCursor_EnumConstantRef = 47, - CXCursor_MemberRef = 48, - CXCursor_LastRef = 48, - - /* Error conditions */ - CXCursor_FirstInvalid = 70, - CXCursor_InvalidFile = 70, - CXCursor_NoDeclFound = 71, - CXCursor_NotImplemented = 72, - CXCursor_LastInvalid = 72 -}; - +/** + * \brief Opaque pointer representing client data that will be passed through + * to various callbacks and visitors. + */ +typedef void *CXClientData; + /** * \brief Provides the contents of a file that has not yet been saved to disk. * @@ -133,27 +98,19 @@ struct CXUnsavedFile { unsigned long Length; }; -/* A cursor into the CXTranslationUnit. */ - -typedef struct { - enum CXCursorKind kind; - CXDecl decl; - CXStmt stmt; /* expression reference */ - CXDecl referringDecl; -} CXCursor; - -/* A unique token for looking up "visible" CXDecls from a CXTranslationUnit. */ -typedef struct { - CXIndex index; - void *data; -} CXEntity; - /** - * For functions returning a string that might or might not need - * to be internally allocated and freed. - * Use clang_getCString to access the C string value. - * Use clang_disposeString to free the value. - * Treat it as an opaque type. + * \defgroup CINDEX_STRING String manipulation routines + * + * @{ + */ + +/** + * \brief A character string. + * + * The \c CXString type is used to return strings from the interface when + * the ownership of that string might different from one call to the next. + * Use \c clang_getCString() to retrieve the string data and, once finished + * with the string data, call \c clang_disposeString() to free the string. */ typedef struct { const char *Spelling; @@ -162,12 +119,20 @@ typedef struct { int MustFreeString; } CXString; -/* Get C string pointer from a CXString. */ +/** + * \brief Retrieve the character data associated with the given string. + */ CINDEX_LINKAGE const char *clang_getCString(CXString string); -/* Free CXString. */ +/** + * \brief Free the given string, + */ CINDEX_LINKAGE void clang_disposeString(CXString string); +/** + * @} + */ + /** * \brief clang_createIndex() provides a shared context for creating * translation units. It provides two options: @@ -191,14 +156,16 @@ CINDEX_LINKAGE void clang_disposeString(CXString string); * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); * * // This will load all the symbols from 'IndexTest.pch' - * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); + * clang_visitChildren(clang_getTranslationUnitCursor(TU), + * TranslationUnitVisitor, 0); * clang_disposeTranslationUnit(TU); * * // This will load all the symbols from 'IndexTest.c', excluding symbols * // from 'IndexTest.pch'. * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); - * clang_loadTranslationUnit(TU, TranslationUnitVisitor, 0); + * clang_visitChildren(clang_getTranslationUnitCursor(TU), + * TranslationUnitVisitor, 0); * clang_disposeTranslationUnit(TU); * * This process of creating the 'pch', loading it separately, and using it (via @@ -211,7 +178,7 @@ CINDEX_LINKAGE void clang_disposeIndex(CXIndex index); CINDEX_LINKAGE CXString clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); -/* +/** * \brief Request that AST's be generated external for API calls which parse * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. * @@ -224,7 +191,7 @@ clang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); CINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, int value); -/* +/** * \brief Create a translation unit from an AST file (-emit-ast). */ CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( @@ -255,137 +222,632 @@ CINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); * * \param source_filename - The name of the source file to load, or NULL if the * source file is included in clang_command_line_args. + * + * \param num_unsaved_files the number of unsaved file entries in \p + * unsaved_files. + * + * \param unsaved_files the files that have not yet been saved to disk + * but may be required for code completion, including the contents of + * those files. */ CINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( - CXIndex CIdx, - const char *source_filename, - int num_clang_command_line_args, - const char **clang_command_line_args -); + CXIndex CIdx, + const char *source_filename, + int num_clang_command_line_args, + const char **clang_command_line_args, + unsigned num_unsaved_files, + struct CXUnsavedFile *unsaved_files); -/* - Usage: clang_loadTranslationUnit(). Will load the toplevel declarations - within a translation unit, issuing a 'callback' for each one. - - void printObjCInterfaceNames(CXTranslationUnit X, CXCursor C) { - if (clang_getCursorKind(C) == Cursor_Declaration) { - CXDecl D = clang_getCursorDecl(C); - if (clang_getDeclKind(D) == CXDecl_ObjC_interface) - printf("@interface %s in file %s on line %d column %d\n", - clang_getDeclSpelling(D), clang_getCursorSource(C), - clang_getCursorLine(C), clang_getCursorColumn(C)); - } - } - static void usage { - clang_loadTranslationUnit(CXTranslationUnit, printObjCInterfaceNames); - } -*/ -typedef void *CXClientData; -typedef void (*CXTranslationUnitIterator)(CXTranslationUnit, CXCursor, - CXClientData); -CINDEX_LINKAGE void clang_loadTranslationUnit(CXTranslationUnit, - CXTranslationUnitIterator, - CXClientData); - -/* - Usage: clang_loadDeclaration(). Will load the declaration, issuing a - 'callback' for each declaration/reference within the respective declaration. - - For interface declarations, this will index the super class, protocols, - ivars, methods, etc. For structure declarations, this will index the fields. - For functions, this will index the parameters (and body, for function - definitions), local declarations/references. - - void getInterfaceDetails(CXDecl X, CXCursor C) { - switch (clang_getCursorKind(C)) { - case Cursor_ObjC_ClassRef: - CXDecl SuperClass = clang_getCursorDecl(C); - case Cursor_ObjC_ProtocolRef: - CXDecl AdoptsProtocol = clang_getCursorDecl(C); - case Cursor_Declaration: - CXDecl AnIvarOrMethod = clang_getCursorDecl(C); - } - } - static void usage() { - if (clang_getDeclKind(D) == CXDecl_ObjC_interface) { - clang_loadDeclaration(D, getInterfaceDetails); - } - } -*/ -typedef void (*CXDeclIterator)(CXDecl, CXCursor, CXClientData); - -CINDEX_LINKAGE void clang_loadDeclaration(CXDecl, CXDeclIterator, CXClientData); - -/* - * CXFile Operations. +/** + * \defgroup CINDEX_FILES File manipulation routines + * + * @{ + */ + +/** + * \brief A particular source file that is part of a translation unit. + */ +typedef void *CXFile; + + +/** + * \brief Retrieve the complete file and path name of the given file. */ CINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); + +/** + * \brief Retrieve the last modification time of the given file. + */ CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); -/* - * CXEntity Operations. +/** + * \brief Retrieve a file handle within the given translation unit. + * + * \param tu the translation unit + * + * \param file_name the name of the file. + * + * \returns the file handle for the named file in the translation unit \p tu, + * or a NULL file handle if the file was not a part of this translation unit. */ +CINDEX_LINKAGE CXFile clang_getFile(CXTranslationUnit tu, + const char *file_name); -/* clang_getDeclaration() maps from a CXEntity to the matching CXDecl (if any) - * in a specified translation unit. */ -CINDEX_LINKAGE CXDecl clang_getDeclaration(CXEntity, CXTranslationUnit); +/** + * @} + */ -/* - * CXDecl Operations. +/** + * \defgroup CINDEX_LOCATIONS Physical source locations + * + * Clang represents physical source locations in its abstract syntax tree in + * great detail, with file, line, and column information for the majority of + * the tokens parsed in the source code. These data types and functions are + * used to represent source location information, either for a particular + * point in the program or for a range of points in the program, and extract + * specific location information from those data types. + * + * @{ */ -CINDEX_LINKAGE CXCursor clang_getCursorFromDecl(CXDecl); -CINDEX_LINKAGE CXEntity clang_getEntityFromDecl(CXIndex, CXDecl); -CINDEX_LINKAGE CXString clang_getDeclSpelling(CXDecl); -CINDEX_LINKAGE unsigned clang_getDeclLine(CXDecl); -CINDEX_LINKAGE unsigned clang_getDeclColumn(CXDecl); -CINDEX_LINKAGE CXString clang_getDeclUSR(CXDecl); -CINDEX_LINKAGE const char *clang_getDeclSource(CXDecl); /* deprecate */ -CINDEX_LINKAGE CXFile clang_getDeclSourceFile(CXDecl); + +/** + * \brief Identifies a specific source location within a translation + * unit. + * + * Use clang_getInstantiationLocation() to map a source location to a + * particular file, line, and column. + */ +typedef struct { + void *ptr_data; + unsigned int_data; +} CXSourceLocation; -typedef struct CXSourceLineColumn { - unsigned line; - unsigned column; -} CXSourceLineColumn; +/** + * \brief Identifies a range of source locations in the source code. + * + * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the + * starting and end locations from a source range, respectively. + */ +typedef struct { + void *ptr_data; + unsigned begin_int_data; + unsigned end_int_data; +} CXSourceRange; + +/** + * \brief Retrieve a NULL (invalid) source location. + */ +CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(); + +/** + * \determine Determine whether two source locations, which must refer into + * the same translation unit, refer to exactly the same point in the source + * code. + * + * \returns non-zero if the source locations refer to the same location, zero + * if they refer to different locations. + */ +CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, + CXSourceLocation loc2); + +/** + * \brief Retrieves the source location associated with a given + * file/line/column in a particular translation unit. + */ +CINDEX_LINKAGE CXSourceLocation clang_getLocation(CXTranslationUnit tu, + CXFile file, + unsigned line, + unsigned column); + +/** + * \brief Retrieve a source range given the beginning and ending source + * locations. + */ +CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, + CXSourceLocation end); + +/** + * \brief Retrieve the file, line, and column represented by the + * given source location. + * + * \param location the location within a source file that will be + * decomposed into its parts. + * + * \param file if non-NULL, will be set to the file to which the given + * source location points. + * + * \param line if non-NULL, will be set to the line to which the given + * source location points. + * + * \param column if non-NULL, will be set to the column to which the + * given source location points. + */ +CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, + CXFile *file, + unsigned *line, + unsigned *column); + +/** + * \brief Retrieve a source location representing the first + * character within a source range. + */ +CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); + +/** + * \brief Retrieve a source location representing the last + * character within a source range. + */ +CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); + +/** + * @} + */ -typedef struct CXDeclExtent { - CXSourceLineColumn begin; - CXSourceLineColumn end; -} CXSourceExtent; +/** + * \brief Describes the kind of entity that a cursor refers to. + */ +enum CXCursorKind { + /* Declarations */ + CXCursor_FirstDecl = 1, + /** + * \brief A declaration whose specific kind is not exposed via this + * interface. + * + * Unexposed declarations have the same operations as any other kind + * of declaration; one can extract their location information, + * spelling, find their definitions, etc. However, the specific kind + * of the declaration is not reported. + */ + CXCursor_UnexposedDecl = 1, + /** \brief A C or C++ struct. */ + CXCursor_StructDecl = 2, + /** \brief A C or C++ union. */ + CXCursor_UnionDecl = 3, + /** \brief A C++ class. */ + CXCursor_ClassDecl = 4, + /** \brief An enumeration. */ + CXCursor_EnumDecl = 5, + /** + * \brief A field (in C) or non-static data member (in C++) in a + * struct, union, or C++ class. + */ + CXCursor_FieldDecl = 6, + /** \brief An enumerator constant. */ + CXCursor_EnumConstantDecl = 7, + /** \brief A function. */ + CXCursor_FunctionDecl = 8, + /** \brief A variable. */ + CXCursor_VarDecl = 9, + /** \brief A function or method parameter. */ + CXCursor_ParmDecl = 10, + /** \brief An Objective-C @interface. */ + CXCursor_ObjCInterfaceDecl = 11, + /** \brief An Objective-C @interface for a category. */ + CXCursor_ObjCCategoryDecl = 12, + /** \brief An Objective-C @protocol declaration. */ + CXCursor_ObjCProtocolDecl = 13, + /** \brief An Objective-C @property declaration. */ + CXCursor_ObjCPropertyDecl = 14, + /** \brief An Objective-C instance variable. */ + CXCursor_ObjCIvarDecl = 15, + /** \brief An Objective-C instance method. */ + CXCursor_ObjCInstanceMethodDecl = 16, + /** \brief An Objective-C class method. */ + CXCursor_ObjCClassMethodDecl = 17, + /** \brief An Objective-C @implementation. */ + CXCursor_ObjCImplementationDecl = 18, + /** \brief An Objective-C @implementation for a category. */ + CXCursor_ObjCCategoryImplDecl = 19, + /** \brief A typedef */ + CXCursor_TypedefDecl = 20, + CXCursor_LastDecl = 20, + + /* References */ + CXCursor_FirstRef = 40, /* Decl references */ + CXCursor_ObjCSuperClassRef = 40, + CXCursor_ObjCProtocolRef = 41, + CXCursor_ObjCClassRef = 42, + /** + * \brief A reference to a type declaration. + * + * A type reference occurs anywhere where a type is named but not + * declared. For example, given: + * + * \code + * typedef unsigned size_type; + * size_type size; + * \endcode + * + * The typedef is a declaration of size_type (CXCursor_TypedefDecl), + * while the type of the variable "size" is referenced. The cursor + * referenced by the type of size is the typedef for size_type. + */ + CXCursor_TypeRef = 43, + CXCursor_LastRef = 43, + + /* Error conditions */ + CXCursor_FirstInvalid = 70, + CXCursor_InvalidFile = 70, + CXCursor_NoDeclFound = 71, + CXCursor_NotImplemented = 72, + CXCursor_LastInvalid = 72, + + /* Expressions */ + CXCursor_FirstExpr = 100, + + /** + * \brief An expression whose specific kind is not exposed via this + * interface. + * + * Unexposed expressions have the same operations as any other kind + * of expression; one can extract their location information, + * spelling, children, etc. However, the specific kind of the + * expression is not reported. + */ + CXCursor_UnexposedExpr = 100, + + /** + * \brief An expression that refers to some value declaration, such + * as a function, varible, or enumerator. + */ + CXCursor_DeclRefExpr = 101, + + /** + * \brief An expression that refers to a member of a struct, union, + * class, Objective-C class, etc. + */ + CXCursor_MemberRefExpr = 102, + + /** \brief An expression that calls a function. */ + CXCursor_CallExpr = 103, + + /** \brief An expression that sends a message to an Objective-C + object or class. */ + CXCursor_ObjCMessageExpr = 104, + CXCursor_LastExpr = 104, + + /* Statements */ + CXCursor_FirstStmt = 200, + /** + * \brief A statement whose specific kind is not exposed via this + * interface. + * + * Unexposed statements have the same operations as any other kind of + * statement; one can extract their location information, spelling, + * children, etc. However, the specific kind of the statement is not + * reported. + */ + CXCursor_UnexposedStmt = 200, + CXCursor_LastStmt = 200, + + /** + * \brief Cursor that represents the translation unit itself. + * + * The translation unit cursor exists primarily to act as the root + * cursor for traversing the contents of a translation unit. + */ + CXCursor_TranslationUnit = 300 +}; -/* clang_getDeclExtent() returns the physical extent of a declaration. The - * beginning line/column pair points to the start of the first token in the - * declaration, and the ending line/column pair points to the last character in - * the last token of the declaration. +/** + * \brief A cursor representing some element in the abstract syntax tree for + * a translation unit. + * + * The cursor abstraction unifies the different kinds of entities in a + * program--declaration, statements, expressions, references to declarations, + * etc.--under a single "cursor" abstraction with a common set of operations. + * Common operation for a cursor include: getting the physical location in + * a source file where the cursor points, getting the name associated with a + * cursor, and retrieving cursors for any child nodes of a particular cursor. + * + * Cursors can be produced in two specific ways. + * clang_getTranslationUnitCursor() produces a cursor for a translation unit, + * from which one can use clang_visitChildren() to explore the rest of the + * translation unit. clang_getCursor() maps from a physical source location + * to the entity that resides at that location, allowing one to map from the + * source code into the AST. */ -CINDEX_LINKAGE CXSourceExtent clang_getDeclExtent(CXDecl); +typedef struct { + enum CXCursorKind kind; + void *data[3]; +} CXCursor; -/* - * CXCursor Operations. +/** + * \defgroup CINDEX_CURSOR_MANIP Cursor manipulations + * + * @{ */ + /** - Usage: clang_getCursor() will translate a source/line/column position - into an AST cursor (to derive semantic information from the source code). + * \brief Retrieve the NULL cursor, which represents no entity. */ -CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, - const char *source_name, - unsigned line, unsigned column); - CINDEX_LINKAGE CXCursor clang_getNullCursor(void); + +/** + * \brief Retrieve the cursor that represents the given translation unit. + * + * The translation unit cursor can be used to start traversing the + * various declarations within the given translation unit. + */ +CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); +/** + * \brief Determine whether two cursors are equivalent. + */ +CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); + +/** + * \brief Retrieve the kind of the given cursor. + */ CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); + +/** + * \brief Determine whether the given cursor kind represents a declaration. + */ CINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); + +/** + * \brief Determine whether the given cursor kind represents a simple + * reference. + * + * Note that other kinds of cursors (such as expressions) can also refer to + * other cursors. Use clang_getCursorReferenced() to determine whether a + * particular cursor refers to another entity. + */ CINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); -CINDEX_LINKAGE unsigned clang_isDefinition(enum CXCursorKind); + +/** + * \brief Determine whether the given cursor kind represents an expression. + */ +CINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); + +/** + * \brief Determine whether the given cursor kind represents a statement. + */ +CINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); + +/** + * \brief Determine whether the given cursor kind represents an invalid + * cursor. + */ CINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); -CINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); +/** + * \brief Determine whether the given cursor kind represents a translation + * unit. + */ +CINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); + +/** + * @} + */ + +/** + * \defgroup CINDEX_CURSOR_SOURCE Mapping between cursors and source code + * + * Cursors represent a location within the Abstract Syntax Tree (AST). These + * routines help map between cursors and the physical locations where the + * described entities occur in the source code. The mapping is provided in + * both directions, so one can map from source code to the AST and back. + * + * @{ + */ + +/** + * \brief Map a source location to the cursor that describes the entity at that + * location in the source code. + * + * clang_getCursor() maps an arbitrary source location within a translation + * unit down to the most specific cursor that describes the entity at that + * location. For example, given an expression \c x + y, invoking + * clang_getCursor() with a source location pointing to "x" will return the + * cursor for "x"; similarly for "y". If the cursor points anywhere between + * "x" or "y" (e.g., on the + or the whitespace around it), clang_getCursor() + * will return a cursor referring to the "+" expression. + * + * \returns a cursor representing the entity at the given source location, or + * a NULL cursor if no such entity can be found. + */ +CINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, CXSourceLocation); + +/** + * \brief Retrieve the physical location of the source constructor referenced + * by the given cursor. + * + * The location of a declaration is typically the location of the name of that + * declaration, where the name of that declaration would occur if it is + * unnamed, or some keyword that introduces that particular declaration. + * The location of a reference is where that reference occurs within the + * source code. + */ +CINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); + +/** + * \brief Retrieve the physical extent of the source construct referenced by + * the given cursor. + * + * The extent of a cursor starts with the file/line/column pointing at the + * first character within the source construct that the cursor refers to and + * ends with the last character withinin that source construct. For a + * declaration, the extent covers the declaration itself. For a reference, + * the extent covers the location of the reference (e.g., where the referenced + * entity was actually used). + */ +CINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); -CINDEX_LINKAGE unsigned clang_getCursorLine(CXCursor); -CINDEX_LINKAGE unsigned clang_getCursorColumn(CXCursor); +/** + * @} + */ + +/** + * \defgroup CINDEX_CURSOR_TRAVERSAL Traversing the AST with cursors + * + * These routines provide the ability to traverse the abstract syntax tree + * using cursors. + * + * @{ + */ + +/** + * \brief Describes how the traversal of the children of a particular + * cursor should proceed after visiting a particular child cursor. + * + * A value of this enumeration type should be returned by each + * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. + */ +enum CXChildVisitResult { + /** + * \brief Terminates the cursor traversal. + */ + CXChildVisit_Break, + /** + * \brief Continues the cursor traversal with the next sibling of + * the cursor just visited, without visiting its children. + */ + CXChildVisit_Continue, + /** + * \brief Recursively traverse the children of this cursor, using + * the same visitor and client data. + */ + CXChildVisit_Recurse +}; + +/** + * \brief Visitor invoked for each cursor found by a traversal. + * + * This visitor function will be invoked for each cursor found by + * clang_visitCursorChildren(). Its first argument is the cursor being + * visited, its second argument is the parent visitor for that cursor, + * and its third argument is the client data provided to + * clang_visitCursorChildren(). + * + * The visitor should return one of the \c CXChildVisitResult values + * to direct clang_visitCursorChildren(). + */ +typedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, + CXCursor parent, + CXClientData client_data); + +/** + * \brief Visit the children of a particular cursor. + * + * This function visits all the direct children of the given cursor, + * invoking the given \p visitor function with the cursors of each + * visited child. The traversal may be recursive, if the visitor returns + * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if + * the visitor returns \c CXChildVisit_Break. + * + * \param tu the translation unit into which the cursor refers. + * + * \param parent the cursor whose child may be visited. All kinds of + * cursors can be visited, including invalid visitors (which, by + * definition, have no children). + * + * \param visitor the visitor function that will be invoked for each + * child of \p parent. + * + * \param client_data pointer data supplied by the client, which will + * be passed to the visitor each time it is invoked. + * + * \returns a non-zero value if the traversal was terminated + * prematurely by the visitor returning \c CXChildVisit_Break. + */ +CINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, + CXCursorVisitor visitor, + CXClientData client_data); + +/** + * @} + */ + +/** + * \defgroup CINDEX_CURSOR_XREF Cross-referencing in the AST + * + * These routines provide the ability to determine references within and + * across translation units, by providing the names of the entities referenced + * by cursors, follow reference cursors to the declarations they reference, + * and associate declarations with their definitions. + * + * @{ + */ + +/** + * \brief Retrieve a Unified Symbol Resolution (USR) for the entity referenced + * by the given cursor. + * + * A Unified Symbol Resolution (USR) is a string that identifies a particular + * entity (function, class, variable, etc.) within a program. USRs can be + * compared across translation units to determine, e.g., when references in + * one translation refer to an entity defined in another translation unit. + */ +CINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); + +/** + * \brief Retrieve a name for the entity referenced by this cursor. + */ CINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); -CINDEX_LINKAGE const char *clang_getCursorSource(CXCursor); /* deprecate */ -CINDEX_LINKAGE CXFile clang_getCursorSourceFile(CXCursor); +/** \brief For a cursor that is a reference, retrieve a cursor representing the + * entity that it references. + * + * Reference cursors refer to other entities in the AST. For example, an + * Objective-C superclass reference cursor refers to an Objective-C class. + * This function produces the cursor for the Objective-C class from the + * cursor for the superclass reference. If the input cursor is a declaration or + * definition, it returns that declaration or definition unchanged. + * Othewise, returns the NULL cursor. + */ +CINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); + +/** + * \brief For a cursor that is either a reference to or a declaration + * of some entity, retrieve a cursor that describes the definition of + * that entity. + * + * Some entities can be declared multiple times within a translation + * unit, but only one of those declarations can also be a + * definition. For example, given: + * + * \code + * int f(int, int); + * int g(int x, int y) { return f(x, y); } + * int f(int a, int b) { return a + b; } + * int f(int, int); + * \endcode + * + * there are three declarations of the function "f", but only the + * second one is a definition. The clang_getCursorDefinition() + * function will take any cursor pointing to a declaration of "f" + * (the first or fourth lines of the example) or a cursor referenced + * that uses "f" (the call to "f' inside "g") and will return a + * declaration cursor pointing to the definition (the second "f" + * declaration). + * + * If given a cursor for which there is no corresponding definition, + * e.g., because there is no definition of that entity within this + * translation unit, returns a NULL cursor. + */ +CINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); + +/** + * \brief Determine whether the declaration pointed to by this cursor + * is also a definition of that entity. + */ +CINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); + +/** + * @} + */ + +/** + * \defgroup CINDEX_DEBUG Debugging facilities + * + * These routines are used for testing and debugging, only, and should not + * be relied upon. + * + * @{ + */ + /* for debug/testing */ CINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, @@ -396,13 +858,22 @@ CINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, unsigned *endLine, unsigned *endColumn); -/* - * If CXCursorKind == Cursor_Reference, then this will return the referenced - * declaration. - * If CXCursorKind == Cursor_Declaration, then this will return the declaration. +/** + * @} */ -CINDEX_LINKAGE CXDecl clang_getCursorDecl(CXCursor); - + +/** + * \defgroup CINDEX_CODE_COMPLET Code completion + * + * Code completion involves taking an (incomplete) source file, along with + * knowledge of where the user is actively editing that file, and suggesting + * syntactically- and semantically-valid constructs that the user might want to + * use at that particular point in the source code. These data structures and + * routines provide support for code completion. + * + * @{ + */ + /** * \brief A semantic string that describes a code-completion result. * @@ -771,6 +1242,27 @@ CXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, CINDEX_LINKAGE void clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); +/** + * @} + */ + + +/** + * \defgroup CINDEX_MISC Miscellaneous utility functions + * + * @{ + */ + +CINDEX_LINKAGE const char *clang_getClangVersion(); + +/** + * @} + */ + +/** + * @} + */ + #ifdef __cplusplus } #endif |
