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