Index.h revision b2cd48756119f4d8d2a865b4b3e0e8efd02e26a0
1d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek/*===-- clang-c/Index.h - Indexing Public C Interface -------------*- C -*-===*\ 2d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* *| 3d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* The LLVM Compiler Infrastructure *| 4d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* *| 5d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* This file is distributed under the University of Illinois Open Source *| 6d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* License. See LICENSE.TXT for details. *| 7d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* *| 8d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|*===----------------------------------------------------------------------===*| 9d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* *| 10d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* This header provides a public inferface to a Clang library for extracting *| 11d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* high-level symbol information from source files without exposing the full *| 12d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* Clang C++ API. *| 13d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek|* *| 14d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek\*===----------------------------------------------------------------------===*/ 15d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek 16d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#ifndef CLANG_C_INDEX_H 17d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#define CLANG_C_INDEX_H 18d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek 1988145034694ed5267fa6fa5febc54fadc02bd479Steve Naroff#include <sys/stat.h> 203d31560343856c573376a04558a7111e7afad4f7Chandler Carruth#include <time.h> 2188145034694ed5267fa6fa5febc54fadc02bd479Steve Naroff 22d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#ifdef __cplusplus 23d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenekextern "C" { 24d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#endif 25d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek 2688145034694ed5267fa6fa5febc54fadc02bd479Steve Naroff/* MSVC DLL import/export. */ 272e06fc877a633abea3b40a64950c7316dac29ca8John Thompson#ifdef _MSC_VER 282e06fc877a633abea3b40a64950c7316dac29ca8John Thompson #ifdef _CINDEX_LIB_ 292e06fc877a633abea3b40a64950c7316dac29ca8John Thompson #define CINDEX_LINKAGE __declspec(dllexport) 302e06fc877a633abea3b40a64950c7316dac29ca8John Thompson #else 312e06fc877a633abea3b40a64950c7316dac29ca8John Thompson #define CINDEX_LINKAGE __declspec(dllimport) 322e06fc877a633abea3b40a64950c7316dac29ca8John Thompson #endif 332e06fc877a633abea3b40a64950c7316dac29ca8John Thompson#else 342e06fc877a633abea3b40a64950c7316dac29ca8John Thompson #define CINDEX_LINKAGE 352e06fc877a633abea3b40a64950c7316dac29ca8John Thompson#endif 362e06fc877a633abea3b40a64950c7316dac29ca8John Thompson 3720d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor/** \defgroup CINDEX C Interface to Clang 3820d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor * 39f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * The C Interface to Clang provides a relatively small API that exposes 40f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * facilities for parsing source code into an abstract syntax tree (AST), 41f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * loading already-parsed ASTs, traversing the AST, associating 42f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * physical source locations with elements within the AST, and other 43f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * facilities that support Clang-based development tools. 44f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * 45f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * This C interface to Clang will never provide all of the information 46f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * representation stored in Clang's C++ AST, nor should it: the intent is to 47f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * maintain an API that is relatively stable from one release to the next, 48f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * providing only the basic functionality needed to support development tools. 49f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * 50f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * To avoid namespace pollution, data types are prefixed with "CX" and 51f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * functions are prefixed with "clang_". 5220d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor * 5320d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor * @{ 5420d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor */ 557f17376e0931a337d544b75d9030bc92763be287Douglas Gregor 567f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 577f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief An "index" that consists of a set of translation units that would 587f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * typically be linked together into an executable or library. 597f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 607f17376e0931a337d544b75d9030bc92763be287Douglas Gregortypedef void *CXIndex; 61600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 627f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 637f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief A single translation unit, which resides in an index. 647f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 6550398199fb10e196a8d92fbf7a062dbe42ed88fdSteve Narofftypedef void *CXTranslationUnit; /* A translation unit instance. */ 66600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 677f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 687f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief Describes the kind of entity that a cursor refers to. 697f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 7089922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroffenum CXCursorKind { 7189922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroff /* Declarations */ 7289922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroff CXCursor_FirstDecl = 1, 7336103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor /** 7436103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * \brief A declaration whose specific kind is not exposed via this 7536103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * interface. 7636103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * 7736103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * Unexposed declarations have the same operations as any other kind 7836103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * of declaration; one can extract their location information, 7936103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * spelling, find their definitions, etc. However, the specific kind 8036103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor * of the declaration is not reported. 8136103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor */ 8236103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor CXCursor_UnexposedDecl = 1, 83301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief A C or C++ struct. */ 84deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_StructDecl = 2, 85301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief A C or C++ union. */ 86deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_UnionDecl = 3, 87301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief A C++ class. */ 88deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ClassDecl = 4, 89301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An enumeration. */ 90deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_EnumDecl = 5, 91301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** 92301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor * \brief A field (in C) or non-static data member (in C++) in a 93301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor * struct, union, or C++ class. 94301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor */ 95deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_FieldDecl = 6, 96301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An enumerator constant. */ 97deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_EnumConstantDecl = 7, 98301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief A function. */ 99deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_FunctionDecl = 8, 100301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief A variable. */ 101deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_VarDecl = 9, 102301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief A function or method parameter. */ 103deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ParmDecl = 10, 104301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C @interface. */ 105deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCInterfaceDecl = 11, 106301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C @interface for a category. */ 107deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCCategoryDecl = 12, 108301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C @protocol declaration. */ 109deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCProtocolDecl = 13, 110301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C @property declaration. */ 111deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCPropertyDecl = 14, 112301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C instance variable. */ 113deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCIvarDecl = 15, 114301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C instance method. */ 115deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCInstanceMethodDecl = 16, 116301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C class method. */ 117deb06bd3566e18f677e76bc435d478b033fe328bTed Kremenek CXCursor_ObjCClassMethodDecl = 17, 118301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C @implementation. */ 119b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor CXCursor_ObjCImplementationDecl = 18, 120301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor /** \brief An Objective-C @implementation for a category. */ 121b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor CXCursor_ObjCCategoryImplDecl = 19, 12236103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor /** \brief A typedef */ 12336103f4d8b79f5e88f359c1fbff13586979866efDouglas Gregor CXCursor_TypedefDecl = 20, 124301221313be4f97327e931ead9794dd3a8bce160Douglas Gregor CXCursor_LastDecl = 20, 12589922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroff 12689922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroff /* References */ 127fb5704295c6137685a7b90b92cd6b958028740c8Steve Naroff CXCursor_FirstRef = 40, /* Decl references */ 128f334b4e3eda5a39f041fe13f805dbb53535daa2fSteve Naroff CXCursor_ObjCSuperClassRef = 40, 129f334b4e3eda5a39f041fe13f805dbb53535daa2fSteve Naroff CXCursor_ObjCProtocolRef = 41, 130fb5704295c6137685a7b90b92cd6b958028740c8Steve Naroff CXCursor_ObjCClassRef = 42, 131e0ca4baa1da58a22bdeb39871535507143ce9079Douglas Gregor CXCursor_LastRef = 42, 13277128ddd3077fc045751a55bb3226802b15d5510Steve Naroff 13377128ddd3077fc045751a55bb3226802b15d5510Steve Naroff /* Error conditions */ 13477128ddd3077fc045751a55bb3226802b15d5510Steve Naroff CXCursor_FirstInvalid = 70, 13577128ddd3077fc045751a55bb3226802b15d5510Steve Naroff CXCursor_InvalidFile = 70, 13677128ddd3077fc045751a55bb3226802b15d5510Steve Naroff CXCursor_NoDeclFound = 71, 13777128ddd3077fc045751a55bb3226802b15d5510Steve Naroff CXCursor_NotImplemented = 72, 13897b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_LastInvalid = 72, 13997b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 14097b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /* Expressions */ 14197b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_FirstExpr = 100, 14297b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 14397b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /** 14497b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * \brief An expression whose specific kind is not exposed via this 14597b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * interface. 14697b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * 14797b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * Unexposed expressions have the same operations as any other kind 14897b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * of expression; one can extract their location information, 14997b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * spelling, children, etc. However, the specific kind of the 15097b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * expression is not reported. 15197b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor */ 15297b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_UnexposedExpr = 100, 15397b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 15497b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /** 15597b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * \brief An expression that refers to some value declaration, such 15697b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * as a function, varible, or enumerator. 15797b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor */ 15897b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_DeclRefExpr = 101, 15997b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 16097b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /** 16197b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * \brief An expression that refers to a member of a struct, union, 16297b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * class, Objective-C class, etc. 16397b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor */ 16497b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_MemberRefExpr = 102, 16597b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 16697b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /** \brief An expression that calls a function. */ 16797b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_CallExpr = 103, 16897b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 16997b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /** \brief An expression that sends a message to an Objective-C 17097b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor object or class. */ 17197b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_ObjCMessageExpr = 104, 17297b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_LastExpr = 104, 17397b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor 17497b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /* Statements */ 17597b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_FirstStmt = 200, 17697b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor /** 17797b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * \brief A statement whose specific kind is not exposed via this 17897b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * interface. 17997b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * 18097b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * Unexposed statements have the same operations as any other kind of 18197b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * statement; one can extract their location information, spelling, 18297b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * children, etc. However, the specific kind of the statement is not 18397b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor * reported. 18497b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor */ 18597b9872d5775446cb8aca1380e437649fe848d91Douglas Gregor CXCursor_UnexposedStmt = 200, 1867eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor CXCursor_LastStmt = 200, 1877eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor 1887eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor /** 1897eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * \brief Cursor that represents the translation unit itself. 1907eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * 1917eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * The translation unit cursor exists primarily to act as the root 1927eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * cursor for traversing the contents of a translation unit. 1937eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor */ 1947eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor CXCursor_TranslationUnit = 300 195600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff}; 196600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 197735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor/** 198735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * \brief Provides the contents of a file that has not yet been saved to disk. 199735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * 200735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * Each CXUnsavedFile instance provides the name of a file on the 201735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * system along with the current contents of that file that have not 202735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * yet been saved to disk. 203735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor */ 204735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregorstruct CXUnsavedFile { 205735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor /** 206735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * \brief The file whose contents have not yet been saved. 207735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * 208735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * This file must already exist in the file system. 209735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor */ 210735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor const char *Filename; 211735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor 212735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor /** 213735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * \brief A null-terminated buffer containing the unsaved contents 214735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * of this file. 215735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor */ 216735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor const char *Contents; 217735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor 218735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor /** 219735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * \brief The length of the unsaved contents of this buffer, not 220735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * counting the NULL at the end of the buffer. 221735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor */ 222735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor unsigned long Length; 223735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor}; 224735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor 2257f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 2267f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief A cursor representing some element in the abstract syntax tree for 2277f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * a translation unit. 2287f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * 2297f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * The cursor abstraction unifies the different kinds of entities in a 2307f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * program--declaration, statements, expressions, references to declarations, 2317f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * etc.--under a single "cursor" abstraction with a common set of operations. 2327f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * Common operation for a cursor include: getting the physical location in 2337f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * a source file where the cursor points, getting the name associated with a 2347f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * cursor, and retrieving cursors for any child nodes of a particular cursor. 2357f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * 2367f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * Cursors can be produced in two specific ways. 2377f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * clang_getTranslationUnitCursor() produces a cursor for a translation unit, 2387f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * from which one can use clang_visitChildren() to explore the rest of the 2397f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * translation unit. clang_getCursor() maps from a physical source location 2407f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * to the entity that resides at that location, allowing one to map from the 2417f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * source code into the AST. 2427f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 24389922f86f4e7da383af2a62ef04ad8b93b941220Steve Narofftypedef struct { 24489922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroff enum CXCursorKind kind; 245283cae37b03047c14ef918503bc46b08405c3b69Douglas Gregor void *data[3]; 24689922f86f4e7da383af2a62ef04ad8b93b941220Steve Naroff} CXCursor; 247600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 248ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff/** 2497f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \defgroup CINDEX_STRING String manipulation routines 2507f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * 2517f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * @{ 2527f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 2537f17376e0931a337d544b75d9030bc92763be287Douglas Gregor 2547f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 2557f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief A character string. 2567f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * 2577f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * The \c CXString type is used to return strings from the interface when 2587f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * the ownership of that string might different from one call to the next. 2597f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * Use \c clang_getCString() to retrieve the string data and, once finished 2607f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * with the string data, call \c clang_disposeString() to free the string. 261ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff */ 262ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Narofftypedef struct { 263ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff const char *Spelling; 264ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff /* A 1 value indicates the clang_ indexing API needed to allocate the string 265ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff (and it must be freed by clang_disposeString()). */ 266ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff int MustFreeString; 267ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff} CXString; 268ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff 2697f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 2707f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief Retrieve the character data associated with the given string. 2717f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 272ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve NaroffCINDEX_LINKAGE const char *clang_getCString(CXString string); 273ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff 2747f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 2757f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * \brief Free the given string, 2767f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 277ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve NaroffCINDEX_LINKAGE void clang_disposeString(CXString string); 278ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve Naroff 2797f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 2807f17376e0931a337d544b75d9030bc92763be287Douglas Gregor * @} 2817f17376e0931a337d544b75d9030bc92763be287Douglas Gregor */ 2827f17376e0931a337d544b75d9030bc92763be287Douglas Gregor 283e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff/** 284e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * \brief clang_createIndex() provides a shared context for creating 285e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * translation units. It provides two options: 286e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * 287e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * - excludeDeclarationsFromPCH: When non-zero, allows enumeration of "local" 288e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * declarations (when loading any new translation units). A "local" declaration 289e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * is one that belongs in the translation unit itself and not in a precompiled 290e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * header that was used by the translation unit. If zero, all declarations 291e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * will be enumerated. 292e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * 293e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * - displayDiagnostics: when non-zero, diagnostics will be output. If zero, 294e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * diagnostics will be ignored. 295b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * 296b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * Here is an example: 297b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * 298b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * // excludeDeclsFromPCH = 1, displayDiagnostics = 1 299b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * Idx = clang_createIndex(1, 1); 300b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * 301b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * // IndexTest.pch was produced with the following command: 302b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * // "clang -x c IndexTest.h -emit-ast -o IndexTest.pch" 303b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * TU = clang_createTranslationUnit(Idx, "IndexTest.pch"); 304b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * 305b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * // This will load all the symbols from 'IndexTest.pch' 306b2cd48756119f4d8d2a865b4b3e0e8efd02e26a0Douglas Gregor * clang_visitChildren(clang_getTranslationUnitCursor(TU), 307002a528ab0189fc60cfbf9328962c96ccbe567eeDouglas Gregor * TranslationUnitVisitor, 0); 308b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * clang_disposeTranslationUnit(TU); 309b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * 310b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * // This will load all the symbols from 'IndexTest.c', excluding symbols 311b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * // from 'IndexTest.pch'. 312b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * char *args[] = { "-Xclang", "-include-pch=IndexTest.pch", 0 }; 313b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * TU = clang_createTranslationUnitFromSourceFile(Idx, "IndexTest.c", 2, args); 314b2cd48756119f4d8d2a865b4b3e0e8efd02e26a0Douglas Gregor * clang_visitChildren(clang_getTranslationUnitCursor(TU), 315b2cd48756119f4d8d2a865b4b3e0e8efd02e26a0Douglas Gregor * TranslationUnitVisitor, 0); 316b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * clang_disposeTranslationUnit(TU); 317b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * 318b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * This process of creating the 'pch', loading it separately, and using it (via 319b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * -include-pch) allows 'excludeDeclsFromPCH' to remove redundant callbacks 320b4ece6377d95e35a8df01cd010d910c34d690f67Steve Naroff * (which gives the indexer the same performance benefit as the compiler). 321e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff */ 3222e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE CXIndex clang_createIndex(int excludeDeclarationsFromPCH, 323e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff int displayDiagnostics); 3248506dde586459887b7e14e23a30af8ac5be5adb6Daniel DunbarCINDEX_LINKAGE void clang_disposeIndex(CXIndex index); 3258506dde586459887b7e14e23a30af8ac5be5adb6Daniel DunbarCINDEX_LINKAGE CXString 3268506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbarclang_getTranslationUnitSpelling(CXTranslationUnit CTUnit); 3278506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar 3287f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 3298506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * \brief Request that AST's be generated external for API calls which parse 3308506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * source code on the fly, e.g. \see createTranslationUnitFromSourceFile. 3318506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * 3328506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * Note: This is for debugging purposes only, and may be removed at a later 3338506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * date. 3348506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * 3358506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * \param index - The index to update. 3368506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * \param value - The new flag value. 3378506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar */ 3388506dde586459887b7e14e23a30af8ac5be5adb6Daniel DunbarCINDEX_LINKAGE void clang_setUseExternalASTGeneration(CXIndex index, 3398506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar int value); 340af08ddc8f1c53fed8d8d0ad82aa2a0bb7d654bd1Steve Naroff 3417f17376e0931a337d544b75d9030bc92763be287Douglas Gregor/** 342e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * \brief Create a translation unit from an AST file (-emit-ast). 343e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff */ 3442e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnit( 345e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff CXIndex, const char *ast_filename 346600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff); 3478506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar 3481374598619f83e6b2de91341a326eae564ece2cbTed Kremenek/** 3491374598619f83e6b2de91341a326eae564ece2cbTed Kremenek * \brief Destroy the specified CXTranslationUnit object. 3501374598619f83e6b2de91341a326eae564ece2cbTed Kremenek */ 3512e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE void clang_disposeTranslationUnit(CXTranslationUnit); 3521374598619f83e6b2de91341a326eae564ece2cbTed Kremenek 3531374598619f83e6b2de91341a326eae564ece2cbTed Kremenek/** 354e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * \brief Return the CXTranslationUnit for a given source file and the provided 355e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * command line arguments one would pass to the compiler. 356e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff * 3578506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * Note: The 'source_filename' argument is optional. If the caller provides a 3588506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * NULL pointer, the name of the source file is expected to reside in the 3598506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * specified command line arguments. 360139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * 3618506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * Note: When encountered in 'clang_command_line_args', the following options 3628506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * are ignored: 363139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * 364139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * '-c' 365139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * '-emit-ast' 366139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * '-fsyntax-only' 367139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * '-o <output file>' (both '-o' and '<output file>' are ignored) 368139ba86a362593da2e350f881e5c7003917aa5a7Ted Kremenek * 3698506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * 3708506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * \param source_filename - The name of the source file to load, or NULL if the 3718506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * source file is included in clang_command_line_args. 3721374598619f83e6b2de91341a326eae564ece2cbTed Kremenek */ 3732e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE CXTranslationUnit clang_createTranslationUnitFromSourceFile( 3748506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar CXIndex CIdx, 3758506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar const char *source_filename, 3765b7d8e254f6c2855b37b5521c0aee0a560dab237Steve Naroff int num_clang_command_line_args, 377e56b4baeba5097852e04bc41ca2e0396cf729955Steve Naroff const char **clang_command_line_args 3785b7d8e254f6c2855b37b5521c0aee0a560dab237Steve Naroff); 379600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 3802b8ee6c2994f738e5162ff46b638974870f51662Steve Narofftypedef void *CXClientData; 381600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 3827eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor/** 3837eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * \brief Retrieve the cursor that represents the given translation unit. 3847eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * 3857eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * The translation unit cursor can be used to start traversing the 3867eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor * various declarations within the given translation unit. 3877eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor */ 3887eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas GregorCINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor(CXTranslationUnit); 3897eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas Gregor 390b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor/** 391b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \brief Describes how the traversal of the children of a particular 392b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * cursor should proceed after visiting a particular child cursor. 393b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 394b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * A value of this enumeration type should be returned by each 395b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \c CXCursorVisitor to indicate how clang_visitChildren() proceed. 396b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor */ 397b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregorenum CXChildVisitResult { 398b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor /** 399b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \brief Terminates the cursor traversal. 400b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor */ 401b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXChildVisit_Break, 402b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor /** 403b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \brief Continues the cursor traversal with the next sibling of 404b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * the cursor just visited, without visiting its children. 405b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor */ 406b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXChildVisit_Continue, 407b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor /** 408b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \brief Recursively traverse the children of this cursor, using 409b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * the same visitor and client data. 410b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor */ 411b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXChildVisit_Recurse 412b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor}; 413b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor 414b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor/** 415b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \brief Visitor invoked for each cursor found by a traversal. 416b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 417b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * This visitor function will be invoked for each cursor found by 418b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * clang_visitCursorChildren(). Its first argument is the cursor being 419b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * visited, its second argument is the parent visitor for that cursor, 420b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * and its third argument is the client data provided to 421b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * clang_visitCursorChildren(). 422b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 423b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * The visitor should return one of the \c CXChildVisitResult values 424b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * to direct clang_visitCursorChildren(). 425b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor */ 426b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregortypedef enum CXChildVisitResult (*CXCursorVisitor)(CXCursor cursor, 427b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXCursor parent, 428b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXClientData client_data); 429b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor 430b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor/** 431b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \brief Visit the children of a particular cursor. 432b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 433b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * This function visits all the direct children of the given cursor, 434b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * invoking the given \p visitor function with the cursors of each 435b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * visited child. The traversal may be recursive, if the visitor returns 436b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \c CXChildVisit_Recurse. The traversal may also be ended prematurely, if 437b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * the visitor returns \c CXChildVisit_Break. 438b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 439b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \param tu the translation unit into which the cursor refers. 440b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 441b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \param parent the cursor whose child may be visited. All kinds of 442b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * cursors can be visited, including invalid visitors (which, by 443b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * definition, have no children). 444b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 445b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \param visitor the visitor function that will be invoked for each 446b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * child of \p parent. 447b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 448b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \param client_data pointer data supplied by the client, which will 449b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * be passed to the visitor each time it is invoked. 450b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * 451b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * \returns a non-zero value if the traversal was terminated 452b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor * prematurely by the visitor returning \c CXChildVisit_Break. 453b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor */ 454b2cd48756119f4d8d2a865b4b3e0e8efd02e26a0Douglas GregorCINDEX_LINKAGE unsigned clang_visitChildren(CXCursor parent, 455b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXCursorVisitor visitor, 456b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor CXClientData client_data); 457b1373d03e4e38620647311bb87e56c0cf7cffeb7Douglas Gregor 458f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 459f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * \defgroup CINDEX_FILES File manipulation routines. 460f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * 461f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * @{ 462f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor */ 463f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 464f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 465f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * \brief A particular source file that is part of a translation unit. 466f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor */ 467f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregortypedef void *CXFile; 468f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 469f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 470f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 471f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * \brief Retrieve the complete file and path name of the given file. 47288145034694ed5267fa6fa5febc54fadc02bd479Steve Naroff */ 47308b0e8daeb683686b876d72674962ad96df21d45Douglas GregorCINDEX_LINKAGE const char *clang_getFileName(CXFile SFile); 474f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 475f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 476f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * \brief Retrieve the last modification time of the given file. 477f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor */ 47808b0e8daeb683686b876d72674962ad96df21d45Douglas GregorCINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); 47988145034694ed5267fa6fa5febc54fadc02bd479Steve Naroff 4803c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor/** 481f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * @} 482f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor */ 483f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 484f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 485f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * \defgroup CINDEX_LOCATIONS Physical source locations 486f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * 487f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * Clang represents physical source locations in its abstract syntax tree in 488f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * great detail, with file, line, and column information for the majority of 489f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * the tokens parsed in the source code. These data types and functions are 490f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * used to represent source location information, either for a particular 491f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * point in the program or for a range of points in the program, and extract 492f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * specific location information from those data types. 493f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * 494f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * @{ 495f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor */ 496f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 497f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 4981db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \brief Identifies a specific source location within a translation 4991db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * unit. 5001db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * 5011db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * Use clang_getInstantiationLocation() to map a source location to a 5021db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * particular file, line, and column. 5033c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor */ 5043c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregortypedef struct { 5051db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor void *ptr_data; 5061db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor unsigned int_data; 5073c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor} CXSourceLocation; 508fe6fd3d41a7f48317d6856c9327b6cead32c3498Ted Kremenek 5093c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor/** 5101db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \brief Identifies a range of source locations in the source code. 5113c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor * 5121db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 5131db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * starting and end locations from a source range, respectively. 5143c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor */ 5153c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregortypedef struct { 5161db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor void *ptr_data; 5171db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor unsigned begin_int_data; 5181db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor unsigned end_int_data; 5193c7313d96cd4a18cd8c1fcd3ddd8128c2fcbe58fDouglas Gregor} CXSourceRange; 520fe6fd3d41a7f48317d6856c9327b6cead32c3498Ted Kremenek 5211db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor/** 5221db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \brief Retrieve the file, line, and column represented by the 5231db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * given source location. 5241db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * 5251db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \param location the location within a source file that will be 5261db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * decomposed into its parts. 5271db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * 5281db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \param file if non-NULL, will be set to the file to which the given 5291db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * source location points. 5301db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * 5311db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \param line if non-NULL, will be set to the line to which the given 5321db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * source location points. 5331db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * 5341db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \param column if non-NULL, will be set to the column to which the 5351db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * given source location points. 5361db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor */ 5371db19dea8d221f27be46332d668d1e2decb7f1abDouglas GregorCINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 5381db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor CXFile *file, 5391db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor unsigned *line, 5401db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor unsigned *column); 5411db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor 5421db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor/** 5431db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \brief Retrieve a source location representing the first 5441db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * character within a source range. 5451db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor */ 5461db19dea8d221f27be46332d668d1e2decb7f1abDouglas GregorCINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 5471db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor 5481db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor/** 5491db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * \brief Retrieve a source location representing the last 5501db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor * character within a source range. 5511db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor */ 5521db19dea8d221f27be46332d668d1e2decb7f1abDouglas GregorCINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 5531db19dea8d221f27be46332d668d1e2decb7f1abDouglas Gregor 554f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor/** 555f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor * @} 556f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor */ 557f55254472e496340cbb4f0a24cff398e441475b5Douglas Gregor 55850398199fb10e196a8d92fbf7a062dbe42ed88fdSteve Naroff/* 55950398199fb10e196a8d92fbf7a062dbe42ed88fdSteve Naroff * CXCursor Operations. 56050398199fb10e196a8d92fbf7a062dbe42ed88fdSteve Naroff */ 5616a6de8b4fc944ca1bfa4e47c516d049a0d627b0eSteve Naroff/** 5626a6de8b4fc944ca1bfa4e47c516d049a0d627b0eSteve Naroff Usage: clang_getCursor() will translate a source/line/column position 5636a6de8b4fc944ca1bfa4e47c516d049a0d627b0eSteve Naroff into an AST cursor (to derive semantic information from the source code). 5646a6de8b4fc944ca1bfa4e47c516d049a0d627b0eSteve Naroff */ 5658506dde586459887b7e14e23a30af8ac5be5adb6Daniel DunbarCINDEX_LINKAGE CXCursor clang_getCursor(CXTranslationUnit, 5668506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar const char *source_name, 5678506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar unsigned line, unsigned column); 568738855554394a6afcf39cc8345fd22c3756b8dd0Ted Kremenek 569738855554394a6afcf39cc8345fd22c3756b8dd0Ted KremenekCINDEX_LINKAGE CXCursor clang_getNullCursor(void); 570fbcb2b716bee88c754684bd189913ed9f8c09086Ted Kremenek 571cf84aa46def41cccf4dd4c51cd0543b70c11e4ebTed Kremenek/* clang_getCursorUSR() returns the USR (if any) associated with entity referred to by the 572cf84aa46def41cccf4dd4c51cd0543b70c11e4ebTed Kremenek * provided CXCursor object. */ 573cf84aa46def41cccf4dd4c51cd0543b70c11e4ebTed KremenekCINDEX_LINKAGE CXString clang_getCursorUSR(CXCursor); 574cf84aa46def41cccf4dd4c51cd0543b70c11e4ebTed Kremenek 5752e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE enum CXCursorKind clang_getCursorKind(CXCursor); 5762e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE unsigned clang_isDeclaration(enum CXCursorKind); 5772e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE unsigned clang_isReference(enum CXCursorKind); 57897b9872d5775446cb8aca1380e437649fe848d91Douglas GregorCINDEX_LINKAGE unsigned clang_isExpression(enum CXCursorKind); 57997b9872d5775446cb8aca1380e437649fe848d91Douglas GregorCINDEX_LINKAGE unsigned clang_isStatement(enum CXCursorKind); 5802e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE unsigned clang_isInvalid(enum CXCursorKind); 5817eaa8ae8692c5cd3eed8cb334fe5346470522091Douglas GregorCINDEX_LINKAGE unsigned clang_isTranslationUnit(enum CXCursorKind); 582738855554394a6afcf39cc8345fd22c3756b8dd0Ted KremenekCINDEX_LINKAGE unsigned clang_equalCursors(CXCursor, CXCursor); 583738855554394a6afcf39cc8345fd22c3756b8dd0Ted Kremenek 584ef0cef6cec8de5fc60e469a93436eed7212e0dc2Steve NaroffCINDEX_LINKAGE CXString clang_getCursorSpelling(CXCursor); 58598258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor 58698258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor/** 58798258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * \brief Retrieve the physical location of the source constructor referenced 58898258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * by the given cursor. 58998258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * 59098258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * The location of a declaration is typically the location of the name of that 59198258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * declaration, where the name of that declaration would occur if it is 59298258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * unnamed, or some keyword that introduces that particular declaration. 59398258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * The location of a reference is where that reference occurs within the 59498258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor * source code. 59598258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor */ 59698258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas GregorCINDEX_LINKAGE CXSourceLocation clang_getCursorLocation(CXCursor); 59798258afae66bab39b0c57a3efb6b20d4fbb5746cDouglas Gregor 598b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor/** 599b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * \brief Retrieve the physical extent of the source construct referenced by 600a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * the given cursor. 601a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * 602a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * The extent of a cursor starts with the file/line/column pointing at the 603a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * first character within the source construct that the cursor refers to and 604a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * ends with the last character withinin that source construct. For a 605a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * declaration, the extent covers the declaration itself. For a reference, 606a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * the extent covers the location of the reference (e.g., where the referenced 607a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor * entity was actually used). 608a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas Gregor */ 609a7bde20f8c6334ccc3a7ef4dd77243d0921a8497Douglas GregorCINDEX_LINKAGE CXSourceRange clang_getCursorExtent(CXCursor); 610c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor 611c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor/** \brief For a cursor that is a reference, retrieve a cursor representing the 612c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * entity that it references. 613c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * 614c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * Reference cursors refer to other entities in the AST. For example, an 615c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * Objective-C superclass reference cursor refers to an Objective-C class. 616c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * This function produces the cursor for the Objective-C class from the 617c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * cursor for the superclass reference. If the input cursor is a declaration or 618c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * definition, it returns that declaration or definition unchanged. 619c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor * Othewise, returns the NULL cursor. 620c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas Gregor */ 621c5d1e9375d71e66d22456e7cc52cc7c0a5c65c3fDouglas GregorCINDEX_LINKAGE CXCursor clang_getCursorReferenced(CXCursor); 622b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor 623b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor/** 624b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * \brief For a cursor that is either a reference to or a declaration 625b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * of some entity, retrieve a cursor that describes the definition of 626b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * that entity. 627b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * 628b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * Some entities can be declared multiple times within a translation 629b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * unit, but only one of those declarations can also be a 630b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * definition. For example, given: 631b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * 632b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * \code 633b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * int f(int, int); 634b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * int g(int x, int y) { return f(x, y); } 635b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * int f(int a, int b) { return a + b; } 636b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * int f(int, int); 637b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * \endcode 638b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * 639b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * there are three declarations of the function "f", but only the 640b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * second one is a definition. The clang_getCursorDefinition() 641b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * function will take any cursor pointing to a declaration of "f" 642b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * (the first or fourth lines of the example) or a cursor referenced 643b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * that uses "f" (the call to "f' inside "g") and will return a 644b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * declaration cursor pointing to the definition (the second "f" 645b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * declaration). 646b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * 647b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * If given a cursor for which there is no corresponding definition, 648b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * e.g., because there is no definition of that entity within this 649b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * translation unit, returns a NULL cursor. 650b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor */ 651b699866820102a69d83d6ac6941985c5ef4e8c40Douglas GregorCINDEX_LINKAGE CXCursor clang_getCursorDefinition(CXCursor); 652b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor 653b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor/** 654b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * \brief Determine whether the declaration pointed to by this cursor 655b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor * is also a definition of that entity. 656b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor */ 657b699866820102a69d83d6ac6941985c5ef4e8c40Douglas GregorCINDEX_LINKAGE unsigned clang_isCursorDefinition(CXCursor); 658b699866820102a69d83d6ac6941985c5ef4e8c40Douglas Gregor 6594ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff/* for debug/testing */ 6602e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE const char *clang_getCursorKindSpelling(enum CXCursorKind Kind); 6612e06fc877a633abea3b40a64950c7316dac29ca8John ThompsonCINDEX_LINKAGE void clang_getDefinitionSpellingAndExtent(CXCursor, 6624ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff const char **startBuf, 6634ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff const char **endBuf, 6644ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff unsigned *startLine, 6654ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff unsigned *startColumn, 6664ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff unsigned *endLine, 6674ade6d6eae934f796ca43c81a5aa185e456dde9bSteve Naroff unsigned *endColumn); 668600866cc7d6d9ec2e27d4b6d6ec461f6463b5ab6Steve Naroff 6690c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 6700c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A semantic string that describes a code-completion result. 6710c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 6720c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * A semantic string that describes the formatting of a code-completion 6730c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * result as a single "template" of text that should be inserted into the 6740c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * source buffer when a particular code-completion result is selected. 6750c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * Each semantic string is made up of some number of "chunks", each of which 6760c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * contains some text along with a description of what that text means, e.g., 6770c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the name of the entity being referenced, whether the text chunk is part of 6780c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the template, or whether it is a "placeholder" that the user should replace 6790c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * with actual code,of a specific kind. See \c CXCompletionChunkKind for a 6800c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * description of the different kinds of chunks. 6810c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 6820c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregortypedef void *CXCompletionString; 6830c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 6840c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 6850c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A single result of code completion. 6860c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 6870c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregortypedef struct { 6880c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 6890c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief The kind of entity that this completion refers to. 6900c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 6910c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * The cursor kind will be a macro, keyword, or a declaration (one of the 6920c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * *Decl cursor kinds), describing the entity that the completion is 6930c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * referring to. 6940c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 6950c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \todo In the future, we would like to provide a full cursor, to allow 6960c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the client to extract additional information from declaration. 6970c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 6980c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor enum CXCursorKind CursorKind; 6990c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 7000c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7010c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief The code-completion string that describes how to insert this 7020c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code-completion result into the editing buffer. 7030c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7040c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionString CompletionString; 7050c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor} CXCompletionResult; 7060c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 7070c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 7080c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Describes a single piece of text within a code-completion string. 7090c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7100c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * Each "chunk" within a code-completion string (\c CXCompletionString) is 7110c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * either a piece of text with a specific "kind" that describes how that text 7120c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * should be interpreted by the client or is another completion string. 7130c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7140c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregorenum CXCompletionChunkKind { 7150c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7160c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A code-completion string that describes "optional" text that 7170c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * could be a part of the template (but is not required). 7180c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7190c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * The Optional chunk is the only kind of chunk that has a code-completion 7200c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * string for its representation, which is accessible via 7210c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \c clang_getCompletionChunkCompletionString(). The code-completion string 7220c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * describes an additional part of the template that is completely optional. 7230c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * For example, optional chunks can be used to describe the placeholders for 7240c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * arguments that match up with defaulted function parameters, e.g. given: 7250c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7260c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \code 7270c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * void f(int x, float y = 3.14, double z = 2.71828); 7280c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \endcode 7290c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7300c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * The code-completion string for this function would contain: 7310c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a TypedText chunk for "f". 7320c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a LeftParen chunk for "(". 7330c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a Placeholder chunk for "int x" 7340c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - an Optional chunk containing the remaining defaulted arguments, e.g., 7350c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a Comma chunk for "," 7360c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a Placeholder chunk for "float x" 7370c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - an Optional chunk containing the last defaulted argument: 7380c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a Comma chunk for "," 7390c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a Placeholder chunk for "double z" 7400c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - a RightParen chunk for ")" 7410c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7420c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * There are many ways two handle Optional chunks. Two simple approaches are: 7430c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - Completely ignore optional chunks, in which case the template for the 7440c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * function "f" would only include the first parameter ("int x"). 7450c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * - Fully expand all optional chunks, in which case the template for the 7460c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * function "f" would have all of the parameters. 7470c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7480c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_Optional, 7490c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7500c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Text that a user would be expected to type to get this 7510c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code-completion result. 7520c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7530c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * There will be exactly one "typed text" chunk in a semantic string, which 7540c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * will typically provide the spelling of a keyword or the name of a 7550c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * declaration that could be used at the current code point. Clients are 7560c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * expected to filter the code-completion results based on the text in this 7570c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * chunk. 7580c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7590c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_TypedText, 7600c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7610c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Text that should be inserted as part of a code-completion result. 7620c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7630c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * A "text" chunk represents text that is part of the template to be 7640c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * inserted into user code should this particular code-completion result 7650c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * be selected. 7660c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7670c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_Text, 7680c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7690c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Placeholder text that should be replaced by the user. 7700c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7710c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * A "placeholder" chunk marks a place where the user should insert text 7720c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * into the code-completion template. For example, placeholders might mark 7730c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the function parameters for a function declaration, to indicate that the 7740c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * user should provide arguments for each of those parameters. The actual 7750c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * text in a placeholder is a suggestion for the text to display before 7760c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the user replaces the placeholder with real code. 7770c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7780c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_Placeholder, 7790c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7800c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Informative text that should be displayed but never inserted as 7810c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * part of the template. 7820c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7830c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * An "informative" chunk contains annotations that can be displayed to 7840c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * help the user decide whether a particular code-completion result is the 7850c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * right option, but which is not part of the actual template to be inserted 7860c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * by code completion. 7870c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 7880c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_Informative, 7890c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 7900c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Text that describes the current parameter when code-completion is 7910c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * referring to function call, message send, or template specialization. 7920c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7930c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * A "current parameter" chunk occurs when code-completion is providing 7940c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * information about a parameter corresponding to the argument at the 7950c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code-completion point. For example, given a function 7960c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 7970c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \code 7980c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * int add(int x, int y); 7990c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \endcode 8000c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8010c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * and the source code \c add(, where the code-completion point is after the 8020c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * "(", the code-completion string will contain a "current parameter" chunk 8030c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * for "int x", indicating that the current argument will initialize that 8040c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * parameter. After typing further, to \c add(17, (where the code-completion 8050c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * point is after the ","), the code-completion string will contain a 8060c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * "current paremeter" chunk to "int y". 8070c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8080c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_CurrentParameter, 8090c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8100c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A left parenthesis ('('), used to initiate a function call or 8110c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * signal the beginning of a function parameter list. 8120c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8130c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_LeftParen, 8140c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8150c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A right parenthesis (')'), used to finish a function call or 8160c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * signal the end of a function parameter list. 8170c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8180c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_RightParen, 8190c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8200c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A left bracket ('['). 8210c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8220c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_LeftBracket, 8230c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8240c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A right bracket (']'). 8250c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8260c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_RightBracket, 8270c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8280c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A left brace ('{'). 8290c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8300c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_LeftBrace, 8310c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8320c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A right brace ('}'). 8330c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8340c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_RightBrace, 8350c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8360c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A left angle bracket ('<'). 8370c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8380c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_LeftAngle, 8390c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8400c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A right angle bracket ('>'). 8410c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8420c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor CXCompletionChunk_RightAngle, 8430c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor /** 8440c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief A comma separator (','). 8450c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 846ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor CXCompletionChunk_Comma, 847ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor /** 848ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor * \brief Text that specifies the result type of a given result. 849ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor * 850ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor * This special kind of informative chunk is not meant to be inserted into 851ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor * the text buffer. Rather, it is meant to illustrate the type that an 852ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor * expression using the given completion string would have. 853ff5ce6eefc7c253ef6edf4d4bfc996fdd82d09aaDouglas Gregor */ 85401dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor CXCompletionChunk_ResultType, 85501dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor /** 85601dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor * \brief A colon (':'). 85701dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor */ 85801dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor CXCompletionChunk_Colon, 85901dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor /** 86001dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor * \brief A semicolon (';'). 86101dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor */ 86201dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor CXCompletionChunk_SemiColon, 86301dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor /** 86401dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor * \brief An '=' sign. 86501dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor */ 86601dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor CXCompletionChunk_Equal, 86701dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor /** 86801dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor * Horizontal space (' '). 86901dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor */ 87001dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor CXCompletionChunk_HorizontalSpace, 87101dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor /** 87201dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor * Vertical space ('\n'), after which it is generally a good idea to 87301dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor * perform indentation. 87401dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor */ 87501dfea02d1da297e8b53db8eea3d3cc652acda8dDouglas Gregor CXCompletionChunk_VerticalSpace 8760c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor}; 8770c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 8780c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 8790c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Determine the kind of a particular chunk within a completion string. 8800c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8810c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param completion_string the completion string to query. 8820c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8830c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param chunk_number the 0-based index of the chunk in the completion string. 8840c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8850c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \returns the kind of the chunk at the index \c chunk_number. 8860c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 8870c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas GregorCINDEX_LINKAGE enum CXCompletionChunkKind 8880c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregorclang_getCompletionChunkKind(CXCompletionString completion_string, 8890c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor unsigned chunk_number); 8900c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 8910c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 8920c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Retrieve the text associated with a particular chunk within a 8930c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * completion string. 8940c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8950c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param completion_string the completion string to query. 8960c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8970c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param chunk_number the 0-based index of the chunk in the completion string. 8980c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 8990c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \returns the text associated with the chunk at index \c chunk_number. 9000c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 9010c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas GregorCINDEX_LINKAGE const char * 9020c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregorclang_getCompletionChunkText(CXCompletionString completion_string, 9030c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor unsigned chunk_number); 9040c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 9050c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 9060c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Retrieve the completion string associated with a particular chunk 9070c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * within a completion string. 9080c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9090c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param completion_string the completion string to query. 9100c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9110c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param chunk_number the 0-based index of the chunk in the completion string. 9120c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9130c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \returns the completion string associated with the chunk at index 9140c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \c chunk_number, or NULL if that chunk is not represented by a completion 9150c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * string. 9160c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 9170c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas GregorCINDEX_LINKAGE CXCompletionString 9180c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregorclang_getCompletionChunkCompletionString(CXCompletionString completion_string, 9190c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor unsigned chunk_number); 9200c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 9210c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 9220c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Retrieve the number of chunks in the given code-completion string. 9230c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 9240c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas GregorCINDEX_LINKAGE unsigned 9250c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregorclang_getNumCompletionChunks(CXCompletionString completion_string); 9260c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 9270c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor/** 928ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \brief Contains the results of code-completion. 929ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * 930ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * This data structure contains the results of code completion, as 931ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * produced by \c clang_codeComplete. Its contents must be freed by 932ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \c clang_disposeCodeCompleteResults. 933ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor */ 934ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregortypedef struct { 935ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor /** 936ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \brief The code-completion results. 937ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor */ 938ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor CXCompletionResult *Results; 939ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor 940ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor /** 941ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \brief The number of code-completion results stored in the 942ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \c Results array. 943ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor */ 944ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor unsigned NumResults; 945ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor} CXCodeCompleteResults; 946ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor 947ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor/** 9480c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \brief Perform code completion at a given location in a source file. 9490c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9500c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * This function performs code completion at a particular file, line, and 9510c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * column within source code, providing results that suggest potential 9520c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code snippets based on the context of the completion. The basic model 9530c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * for code completion is that Clang will parse a complete source file, 9540c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * performing syntax checking up to the location where code-completion has 9550c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * been requested. At that point, a special code-completion token is passed 9560c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * to the parser, which recognizes this token and determines, based on the 9570c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * current location in the C/Objective-C/C++ grammar and the state of 9580c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * semantic analysis, what completions to provide. These completions are 959ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * returned via a new \c CXCodeCompleteResults structure. 9600c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9610c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * Code completion itself is meant to be triggered by the client when the 9620c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * user types punctuation characters or whitespace, at which point the 9630c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code-completion location will coincide with the cursor. For example, if \c p 9640c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * is a pointer, code-completion might be triggered after the "-" and then 9650c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * after the ">" in \c p->. When the code-completion location is afer the ">", 9660c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the completion results will provide, e.g., the members of the struct that 9670c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * "p" points to. The client is responsible for placing the cursor at the 9680c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * beginning of the token currently being typed, then filtering the results 9690c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * based on the contents of the token. For example, when code-completing for 9700c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the expression \c p->get, the client should provide the location just after 9710c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the 9720c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * client can filter the results based on the current token text ("get"), only 9730c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * showing those results that start with "get". The intent of this interface 974ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * is to separate the relatively high-latency acquisition of code-completion 9750c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * results from the filtering of results on a per-character basis, which must 9760c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * have a lower latency. 9770c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9780c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param CIdx the \c CXIndex instance that will be used to perform code 9790c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * completion. 9800c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9818506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * \param source_filename the name of the source file that should be parsed to 9828506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * perform code-completion. This source file must be the same as or include the 9838506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * filename described by \p complete_filename, or no code-completion results 9848506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * will be produced. NOTE: One can also specify NULL for this argument if the 9858506dde586459887b7e14e23a30af8ac5be5adb6Daniel Dunbar * source file is included in command_line_args. 9860c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9870c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param num_command_line_args the number of command-line arguments stored in 9880c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \p command_line_args. 9890c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 9900c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param command_line_args the command-line arguments to pass to the Clang 9910c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * compiler to build the given source file. This should include all of the 9920c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * necessary include paths, language-dialect switches, precompiled header 9930c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * includes, etc., but should not include any information specific to 9940c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code completion. 9950c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 996735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * \param num_unsaved_files the number of unsaved file entries in \p 997735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * unsaved_files. 998735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * 999735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * \param unsaved_files the files that have not yet been saved to disk 1000735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * but may be required for code completion, including the contents of 1001735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * those files. 1002735df88a38e80c1ca70daa889aa516b8b9f54b50Douglas Gregor * 10030c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param complete_filename the name of the source file where code completion 10040c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * should be performed. In many cases, this name will be the same as the 10050c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * source filename. However, the completion filename may also be a file 10060c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * included by the source file, which is required when producing 10070c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * code-completion results for a header. 10080c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 10090c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param complete_line the line at which code-completion should occur. 10100c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 10110c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * \param complete_column the column at which code-completion should occur. 10120c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * Note that the column should point just after the syntactic construct that 10130c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * initiated code completion, and not in the middle of a lexical token. 10140c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor * 1015ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \returns if successful, a new CXCodeCompleteResults structure 1016ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * containing code-completion results, which should eventually be 1017ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * freed with \c clang_disposeCodeCompleteResults(). If code 1018ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * completion fails, returns NULL. 1019ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor */ 1020ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas GregorCINDEX_LINKAGE 1021ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas GregorCXCodeCompleteResults *clang_codeComplete(CXIndex CIdx, 1022ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor const char *source_filename, 1023ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor int num_command_line_args, 1024ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor const char **command_line_args, 1025ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor unsigned num_unsaved_files, 1026ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor struct CXUnsavedFile *unsaved_files, 1027ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor const char *complete_filename, 1028ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor unsigned complete_line, 1029ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor unsigned complete_column); 1030ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor 1031ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor/** 1032ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregor * \brief Free the given set of code-completion results. 10330c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor */ 1034ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas GregorCINDEX_LINKAGE 1035ec6762c709726bf2ee5f76c21df81e71a56e6f81Douglas Gregorvoid clang_disposeCodeCompleteResults(CXCodeCompleteResults *Results); 10360c8296dfb495f41d6f0de6fe1d03014ffd063674Douglas Gregor 103720d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor/** 103820d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor * @} 103920d416c36b46dd19ee0b1ea2d0266ae43be86e51Douglas Gregor */ 1040d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#ifdef __cplusplus 1041d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek} 1042d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#endif 1043d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek#endif 1044d2fa56687f8bd5ac6ebf9d9468d0efd714986a54Ted Kremenek 1045