297 lines · c
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_H15#define LLVM_CLANG_C_CXSOURCE_LOCATION_H16 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 22LLVM_CLANG_C_EXTERN_C_BEGIN23 24/**25 * \defgroup CINDEX_LOCATIONS Physical source locations26 *27 * Clang represents physical source locations in its abstract syntax tree in28 * great detail, with file, line, and column information for the majority of29 * the tokens parsed in the source code. These data types and functions are30 * used to represent source location information, either for a particular31 * point in the program or for a range of points in the program, and extract32 * specific location information from those data types.33 *34 * @{35 */36 37/**38 * Identifies a specific source location within a translation39 * unit.40 *41 * Use clang_getExpansionLocation() or clang_getSpellingLocation()42 * to map a source location to a particular file, line, and column.43 */44typedef 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 the53 * starting and end locations from a source range, respectively.54 */55typedef 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 */64CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void);65 66/**67 * Determine whether two source locations, which must refer into68 * the same translation unit, refer to exactly the same point in the source69 * code.70 *71 * \returns non-zero if the source locations refer to the same location, zero72 * if they refer to different locations.73 */74CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,75 CXSourceLocation loc2);76 77/**78 * Determine for two source locations if the first comes79 * strictly before the second one in the source code.80 *81 * \returns non-zero if the first source location comes82 * strictly before the second one, zero otherwise.83 */84CINDEX_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 */90CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location);91 92/**93 * Returns non-zero if the given source location is in the main file of94 * the corresponding translation unit.95 */96CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location);97 98/**99 * Retrieve a NULL (invalid) source range.100 */101CINDEX_LINKAGE CXSourceRange clang_getNullRange(void);102 103/**104 * Retrieve a source range given the beginning and ending source105 * locations.106 */107CINDEX_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 */115CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1,116 CXSourceRange range2);117 118/**119 * Returns non-zero if \p range is null.120 */121CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range);122 123/**124 * Retrieve the file, line, column, and offset represented by125 * the given source location.126 *127 * If the location refers into a macro expansion, retrieves the128 * location of the macro expansion.129 *130 * \param location the location within a source file that will be decomposed131 * into its parts.132 *133 * \param file [out] if non-NULL, will be set to the file to which the given134 * source location points.135 *136 * \param line [out] if non-NULL, will be set to the line to which the given137 * source location points.138 *139 * \param column [out] if non-NULL, will be set to the column to which the given140 * source location points.141 *142 * \param offset [out] if non-NULL, will be set to the offset into the143 * buffer to which the given source location points.144 */145CINDEX_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 source152 * location, as specified in a # line directive.153 *154 * Example: given the following source code in a file somefile.c155 *156 * \code157 * #123 "dummy.c" 1158 *159 * static int func(void)160 * {161 * return 0;162 * }163 * \endcode164 *165 * the location information returned by this function would be166 *167 * File: dummy.c Line: 124 Column: 12168 *169 * whereas clang_getExpansionLocation would have returned170 *171 * File: somefile.c Line: 3 Column: 12172 *173 * \param location the location within a source file that will be decomposed174 * into its parts.175 *176 * \param filename [out] if non-NULL, will be set to the filename of the177 * source location. Note that filenames returned will be for "virtual" files,178 * which don't necessarily exist on the machine running clang - e.g. when179 * parsing preprocessed output obtained from a different environment. If180 * a non-NULL value is passed in, remember to dispose of the returned value181 * using \c clang_disposeString() once you've finished with it. For an invalid182 * source location, an empty string is returned.183 *184 * \param line [out] if non-NULL, will be set to the line number of the185 * 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 the188 * source location. For an invalid source location, zero is returned.189 */190CINDEX_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 represented196 * by the given source location.197 *198 * This interface has been replaced by the newer interface199 * #clang_getExpansionLocation(). See that interface's documentation for200 * details.201 */202CINDEX_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 by209 * the given source location.210 *211 * If the location refers into a macro instantiation, return where the212 * location was originally spelled in the source file.213 *214 * \param location the location within a source file that will be decomposed215 * into its parts.216 *217 * \param file [out] if non-NULL, will be set to the file to which the given218 * source location points.219 *220 * \param line [out] if non-NULL, will be set to the line to which the given221 * source location points.222 *223 * \param column [out] if non-NULL, will be set to the column to which the given224 * source location points.225 *226 * \param offset [out] if non-NULL, will be set to the offset into the227 * buffer to which the given source location points.228 */229CINDEX_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 by236 * the given source location.237 *238 * If the location refers into a macro expansion, return where the macro was239 * expanded or where the macro argument was written, if the location points at240 * a macro argument.241 *242 * \param location the location within a source file that will be decomposed243 * into its parts.244 *245 * \param file [out] if non-NULL, will be set to the file to which the given246 * source location points.247 *248 * \param line [out] if non-NULL, will be set to the line to which the given249 * source location points.250 *251 * \param column [out] if non-NULL, will be set to the column to which the given252 * source location points.253 *254 * \param offset [out] if non-NULL, will be set to the offset into the255 * buffer to which the given source location points.256 */257CINDEX_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 a263 * source range.264 */265CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);266 267/**268 * Retrieve a source location representing the last character within a269 * source range.270 */271CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);272 273/**274 * Identifies an array of ranges.275 */276typedef 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 */288CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges);289 290/**291 * @}292 */293 294LLVM_CLANG_C_EXTERN_C_END295 296#endif297