1 /*===-- clang-c/CXSourceLocation.h - C Index Source Location ------*- C -*-===*\ 2 |* *| 3 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| 4 |* Exceptions. *| 5 |* See https://llvm.org/LICENSE.txt for license information. *| 6 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| 7 |* *| 8 |*===----------------------------------------------------------------------===*| 9 |* *| 10 |* This header provides the interface to C Index source locations. *| 11 |* *| 12 \*===----------------------------------------------------------------------===*/ 13 14 #ifndef LLVM_CLANG_C_CXSOURCE_LOCATION_H 15 #define LLVM_CLANG_C_CXSOURCE_LOCATION_H 16 17 #include "clang-c/CXFile.h" 18 #include "clang-c/CXString.h" 19 #include "clang-c/ExternC.h" 20 #include "clang-c/Platform.h" 21 22 LLVM_CLANG_C_EXTERN_C_BEGIN 23 24 /** 25 * \defgroup CINDEX_LOCATIONS Physical source locations 26 * 27 * Clang represents physical source locations in its abstract syntax tree in 28 * great detail, with file, line, and column information for the majority of 29 * the tokens parsed in the source code. These data types and functions are 30 * used to represent source location information, either for a particular 31 * point in the program or for a range of points in the program, and extract 32 * specific location information from those data types. 33 * 34 * @{ 35 */ 36 37 /** 38 * Identifies a specific source location within a translation 39 * unit. 40 * 41 * Use clang_getExpansionLocation() or clang_getSpellingLocation() 42 * to map a source location to a particular file, line, and column. 43 */ 44 typedef struct { 45 const void *ptr_data[2]; 46 unsigned int_data; 47 } CXSourceLocation; 48 49 /** 50 * Identifies a half-open character range in the source code. 51 * 52 * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the 53 * starting and end locations from a source range, respectively. 54 */ 55 typedef struct { 56 const void *ptr_data[2]; 57 unsigned begin_int_data; 58 unsigned end_int_data; 59 } CXSourceRange; 60 61 /** 62 * Retrieve a NULL (invalid) source location. 63 */ 64 CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); 65 66 /** 67 * Determine whether two source locations, which must refer into 68 * the same translation unit, refer to exactly the same point in the source 69 * code. 70 * 71 * \returns non-zero if the source locations refer to the same location, zero 72 * if they refer to different locations. 73 */ 74 CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, 75 CXSourceLocation loc2); 76 77 /** 78 * Returns non-zero if the given source location is in a system header. 79 */ 80 CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); 81 82 /** 83 * Returns non-zero if the given source location is in the main file of 84 * the corresponding translation unit. 85 */ 86 CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); 87 88 /** 89 * Retrieve a NULL (invalid) source range. 90 */ 91 CINDEX_LINKAGE CXSourceRange clang_getNullRange(void); 92 93 /** 94 * Retrieve a source range given the beginning and ending source 95 * locations. 96 */ 97 CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 98 CXSourceLocation end); 99 100 /** 101 * Determine whether two ranges are equivalent. 102 * 103 * \returns non-zero if the ranges are the same, zero if they differ. 104 */ 105 CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, 106 CXSourceRange range2); 107 108 /** 109 * Returns non-zero if \p range is null. 110 */ 111 CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); 112 113 /** 114 * Retrieve the file, line, column, and offset represented by 115 * the given source location. 116 * 117 * If the location refers into a macro expansion, retrieves the 118 * location of the macro expansion. 119 * 120 * \param location the location within a source file that will be decomposed 121 * into its parts. 122 * 123 * \param file [out] if non-NULL, will be set to the file to which the given 124 * source location points. 125 * 126 * \param line [out] if non-NULL, will be set to the line to which the given 127 * source location points. 128 * 129 * \param column [out] if non-NULL, will be set to the column to which the given 130 * source location points. 131 * 132 * \param offset [out] if non-NULL, will be set to the offset into the 133 * buffer to which the given source location points. 134 */ 135 CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, 136 CXFile *file, unsigned *line, 137 unsigned *column, 138 unsigned *offset); 139 140 /** 141 * Retrieve the file, line and column represented by the given source 142 * location, as specified in a # line directive. 143 * 144 * Example: given the following source code in a file somefile.c 145 * 146 * \code 147 * #123 "dummy.c" 1 148 * 149 * static int func(void) 150 * { 151 * return 0; 152 * } 153 * \endcode 154 * 155 * the location information returned by this function would be 156 * 157 * File: dummy.c Line: 124 Column: 12 158 * 159 * whereas clang_getExpansionLocation would have returned 160 * 161 * File: somefile.c Line: 3 Column: 12 162 * 163 * \param location the location within a source file that will be decomposed 164 * into its parts. 165 * 166 * \param filename [out] if non-NULL, will be set to the filename of the 167 * source location. Note that filenames returned will be for "virtual" files, 168 * which don't necessarily exist on the machine running clang - e.g. when 169 * parsing preprocessed output obtained from a different environment. If 170 * a non-NULL value is passed in, remember to dispose of the returned value 171 * using \c clang_disposeString() once you've finished with it. For an invalid 172 * source location, an empty string is returned. 173 * 174 * \param line [out] if non-NULL, will be set to the line number of the 175 * source location. For an invalid source location, zero is returned. 176 * 177 * \param column [out] if non-NULL, will be set to the column number of the 178 * source location. For an invalid source location, zero is returned. 179 */ 180 CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, 181 CXString *filename, 182 unsigned *line, unsigned *column); 183 184 /** 185 * Legacy API to retrieve the file, line, column, and offset represented 186 * by the given source location. 187 * 188 * This interface has been replaced by the newer interface 189 * #clang_getExpansionLocation(). See that interface's documentation for 190 * details. 191 */ 192 CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 193 CXFile *file, unsigned *line, 194 unsigned *column, 195 unsigned *offset); 196 197 /** 198 * Retrieve the file, line, column, and offset represented by 199 * the given source location. 200 * 201 * If the location refers into a macro instantiation, return where the 202 * location was originally spelled in the source file. 203 * 204 * \param location the location within a source file that will be decomposed 205 * into its parts. 206 * 207 * \param file [out] if non-NULL, will be set to the file to which the given 208 * source location points. 209 * 210 * \param line [out] if non-NULL, will be set to the line to which the given 211 * source location points. 212 * 213 * \param column [out] if non-NULL, will be set to the column to which the given 214 * source location points. 215 * 216 * \param offset [out] if non-NULL, will be set to the offset into the 217 * buffer to which the given source location points. 218 */ 219 CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, 220 CXFile *file, unsigned *line, 221 unsigned *column, 222 unsigned *offset); 223 224 /** 225 * Retrieve the file, line, column, and offset represented by 226 * the given source location. 227 * 228 * If the location refers into a macro expansion, return where the macro was 229 * expanded or where the macro argument was written, if the location points at 230 * a macro argument. 231 * 232 * \param location the location within a source file that will be decomposed 233 * into its parts. 234 * 235 * \param file [out] if non-NULL, will be set to the file to which the given 236 * source location points. 237 * 238 * \param line [out] if non-NULL, will be set to the line to which the given 239 * source location points. 240 * 241 * \param column [out] if non-NULL, will be set to the column to which the given 242 * source location points. 243 * 244 * \param offset [out] if non-NULL, will be set to the offset into the 245 * buffer to which the given source location points. 246 */ 247 CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, 248 CXFile *file, unsigned *line, 249 unsigned *column, unsigned *offset); 250 251 /** 252 * Retrieve a source location representing the first character within a 253 * source range. 254 */ 255 CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 256 257 /** 258 * Retrieve a source location representing the last character within a 259 * source range. 260 */ 261 CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 262 263 /** 264 * Identifies an array of ranges. 265 */ 266 typedef struct { 267 /** The number of ranges in the \c ranges array. */ 268 unsigned count; 269 /** 270 * An array of \c CXSourceRanges. 271 */ 272 CXSourceRange *ranges; 273 } CXSourceRangeList; 274 275 /** 276 * Destroy the given \c CXSourceRangeList. 277 */ 278 CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); 279 280 /** 281 * @} 282 */ 283 284 LLVM_CLANG_C_EXTERN_C_END 285 286 #endif 287