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 * Determine for two source locations if the first comes 79 * strictly before the second one in the source code. 80 * 81 * \returns non-zero if the first source location comes 82 * strictly before the second one, zero otherwise. 83 */ 84 CINDEX_LINKAGE unsigned clang_isBeforeInTranslationUnit(CXSourceLocation loc1, 85 CXSourceLocation loc2); 86 87 /** 88 * Returns non-zero if the given source location is in a system header. 89 */ 90 CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); 91 92 /** 93 * Returns non-zero if the given source location is in the main file of 94 * the corresponding translation unit. 95 */ 96 CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); 97 98 /** 99 * Retrieve a NULL (invalid) source range. 100 */ 101 CINDEX_LINKAGE CXSourceRange clang_getNullRange(void); 102 103 /** 104 * Retrieve a source range given the beginning and ending source 105 * locations. 106 */ 107 CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, 108 CXSourceLocation end); 109 110 /** 111 * Determine whether two ranges are equivalent. 112 * 113 * \returns non-zero if the ranges are the same, zero if they differ. 114 */ 115 CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, 116 CXSourceRange range2); 117 118 /** 119 * Returns non-zero if \p range is null. 120 */ 121 CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); 122 123 /** 124 * Retrieve the file, line, column, and offset represented by 125 * the given source location. 126 * 127 * If the location refers into a macro expansion, retrieves the 128 * location of the macro expansion. 129 * 130 * \param location the location within a source file that will be decomposed 131 * into its parts. 132 * 133 * \param file [out] if non-NULL, will be set to the file to which the given 134 * source location points. 135 * 136 * \param line [out] if non-NULL, will be set to the line to which the given 137 * source location points. 138 * 139 * \param column [out] if non-NULL, will be set to the column to which the given 140 * source location points. 141 * 142 * \param offset [out] if non-NULL, will be set to the offset into the 143 * buffer to which the given source location points. 144 */ 145 CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, 146 CXFile *file, unsigned *line, 147 unsigned *column, 148 unsigned *offset); 149 150 /** 151 * Retrieve the file, line and column represented by the given source 152 * location, as specified in a # line directive. 153 * 154 * Example: given the following source code in a file somefile.c 155 * 156 * \code 157 * #123 "dummy.c" 1 158 * 159 * static int func(void) 160 * { 161 * return 0; 162 * } 163 * \endcode 164 * 165 * the location information returned by this function would be 166 * 167 * File: dummy.c Line: 124 Column: 12 168 * 169 * whereas clang_getExpansionLocation would have returned 170 * 171 * File: somefile.c Line: 3 Column: 12 172 * 173 * \param location the location within a source file that will be decomposed 174 * into its parts. 175 * 176 * \param filename [out] if non-NULL, will be set to the filename of the 177 * source location. Note that filenames returned will be for "virtual" files, 178 * which don't necessarily exist on the machine running clang - e.g. when 179 * parsing preprocessed output obtained from a different environment. If 180 * a non-NULL value is passed in, remember to dispose of the returned value 181 * using \c clang_disposeString() once you've finished with it. For an invalid 182 * source location, an empty string is returned. 183 * 184 * \param line [out] if non-NULL, will be set to the line number of the 185 * source location. For an invalid source location, zero is returned. 186 * 187 * \param column [out] if non-NULL, will be set to the column number of the 188 * source location. For an invalid source location, zero is returned. 189 */ 190 CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, 191 CXString *filename, 192 unsigned *line, unsigned *column); 193 194 /** 195 * Legacy API to retrieve the file, line, column, and offset represented 196 * by the given source location. 197 * 198 * This interface has been replaced by the newer interface 199 * #clang_getExpansionLocation(). See that interface's documentation for 200 * details. 201 */ 202 CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, 203 CXFile *file, unsigned *line, 204 unsigned *column, 205 unsigned *offset); 206 207 /** 208 * Retrieve the file, line, column, and offset represented by 209 * the given source location. 210 * 211 * If the location refers into a macro instantiation, return where the 212 * location was originally spelled in the source file. 213 * 214 * \param location the location within a source file that will be decomposed 215 * into its parts. 216 * 217 * \param file [out] if non-NULL, will be set to the file to which the given 218 * source location points. 219 * 220 * \param line [out] if non-NULL, will be set to the line to which the given 221 * source location points. 222 * 223 * \param column [out] if non-NULL, will be set to the column to which the given 224 * source location points. 225 * 226 * \param offset [out] if non-NULL, will be set to the offset into the 227 * buffer to which the given source location points. 228 */ 229 CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, 230 CXFile *file, unsigned *line, 231 unsigned *column, 232 unsigned *offset); 233 234 /** 235 * Retrieve the file, line, column, and offset represented by 236 * the given source location. 237 * 238 * If the location refers into a macro expansion, return where the macro was 239 * expanded or where the macro argument was written, if the location points at 240 * a macro argument. 241 * 242 * \param location the location within a source file that will be decomposed 243 * into its parts. 244 * 245 * \param file [out] if non-NULL, will be set to the file to which the given 246 * source location points. 247 * 248 * \param line [out] if non-NULL, will be set to the line to which the given 249 * source location points. 250 * 251 * \param column [out] if non-NULL, will be set to the column to which the given 252 * source location points. 253 * 254 * \param offset [out] if non-NULL, will be set to the offset into the 255 * buffer to which the given source location points. 256 */ 257 CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, 258 CXFile *file, unsigned *line, 259 unsigned *column, unsigned *offset); 260 261 /** 262 * Retrieve a source location representing the first character within a 263 * source range. 264 */ 265 CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); 266 267 /** 268 * Retrieve a source location representing the last character within a 269 * source range. 270 */ 271 CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); 272 273 /** 274 * Identifies an array of ranges. 275 */ 276 typedef struct { 277 /** The number of ranges in the \c ranges array. */ 278 unsigned count; 279 /** 280 * An array of \c CXSourceRanges. 281 */ 282 CXSourceRange *ranges; 283 } CXSourceRangeList; 284 285 /** 286 * Destroy the given \c CXSourceRangeList. 287 */ 288 CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); 289 290 /** 291 * @} 292 */ 293 294 LLVM_CLANG_C_EXTERN_C_END 295 296 #endif 297