clang/include/clang-c/CXSourceLocation.h

   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