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  * 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