include/clang-c/CXSourceLocation.h

0001 /*===-- clang-c/CXSourceLocation.h - C Index Source Location ------*- C -*-===*\
0002 |*                                                                            *|
0003 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
0004 |* Exceptions.                                                                *|
0005 |* See https://llvm.org/LICENSE.txt for license information.                  *|
0006 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
0007 |*                                                                            *|
0008 |*===----------------------------------------------------------------------===*|
0009 |*                                                                            *|
0010 |* This header provides the interface to C Index source locations.            *|
0011 |*                                                                            *|
0012 \*===----------------------------------------------------------------------===*/
0013
0014 #ifndef LLVM_CLANG_C_CXSOURCE_LOCATION_H
0015 #define LLVM_CLANG_C_CXSOURCE_LOCATION_H
0016
0017 #include "clang-c/CXFile.h"
0018 #include "clang-c/CXString.h"
0019 #include "clang-c/ExternC.h"
0020 #include "clang-c/Platform.h"
0021
0022 LLVM_CLANG_C_EXTERN_C_BEGIN
0023
0024 /**
0025  * \defgroup CINDEX_LOCATIONS Physical source locations
0026  *
0027  * Clang represents physical source locations in its abstract syntax tree in
0028  * great detail, with file, line, and column information for the majority of
0029  * the tokens parsed in the source code. These data types and functions are
0030  * used to represent source location information, either for a particular
0031  * point in the program or for a range of points in the program, and extract
0032  * specific location information from those data types.
0033  *
0034  * @{
0035  */
0036
0037 /**
0038  * Identifies a specific source location within a translation
0039  * unit.
0040  *
0041  * Use clang_getExpansionLocation() or clang_getSpellingLocation()
0042  * to map a source location to a particular file, line, and column.
0043  */
0044 typedef struct {
0045   const void *ptr_data[2];
0046   unsigned int_data;
0047 } CXSourceLocation;
0048
0049 /**
0050  * Identifies a half-open character range in the source code.
0051  *
0052  * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the
0053  * starting and end locations from a source range, respectively.
0054  */
0055 typedef struct {
0056   const void *ptr_data[2];
0057   unsigned begin_int_data;
0058   unsigned end_int_data;
0059 } CXSourceRange;
0060
0061 /**
0062  * Retrieve a NULL (invalid) source location.
0063  */
0064 CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void);
0065
0066 /**
0067  * Determine whether two source locations, which must refer into
0068  * the same translation unit, refer to exactly the same point in the source
0069  * code.
0070  *
0071  * \returns non-zero if the source locations refer to the same location, zero
0072  * if they refer to different locations.
0073  */
0074 CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1,
0075                                              CXSourceLocation loc2);
0076
0077 /**
0078  * Determine for two source locations if the first comes
0079  * strictly before the second one in the source code.
0080  *
0081  * \returns non-zero if the first source location comes
0082  * strictly before the second one, zero otherwise.
0083  */
0084 CINDEX_LINKAGE unsigned clang_isBeforeInTranslationUnit(CXSourceLocation loc1,
0085                                                         CXSourceLocation loc2);
0086
0087 /**
0088  * Returns non-zero if the given source location is in a system header.
0089  */
0090 CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location);
0091
0092 /**
0093  * Returns non-zero if the given source location is in the main file of
0094  * the corresponding translation unit.
0095  */
0096 CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location);
0097
0098 /**
0099  * Retrieve a NULL (invalid) source range.
0100  */
0101 CINDEX_LINKAGE CXSourceRange clang_getNullRange(void);
0102
0103 /**
0104  * Retrieve a source range given the beginning and ending source
0105  * locations.
0106  */
0107 CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin,
0108                                             CXSourceLocation end);
0109
0110 /**
0111  * Determine whether two ranges are equivalent.
0112  *
0113  * \returns non-zero if the ranges are the same, zero if they differ.
0114  */
0115 CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1,
0116                                           CXSourceRange range2);
0117
0118 /**
0119  * Returns non-zero if \p range is null.
0120  */
0121 CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range);
0122
0123 /**
0124  * Retrieve the file, line, column, and offset represented by
0125  * the given source location.
0126  *
0127  * If the location refers into a macro expansion, retrieves the
0128  * location of the macro expansion.
0129  *
0130  * \param location the location within a source file that will be decomposed
0131  * into its parts.
0132  *
0133  * \param file [out] if non-NULL, will be set to the file to which the given
0134  * source location points.
0135  *
0136  * \param line [out] if non-NULL, will be set to the line to which the given
0137  * source location points.
0138  *
0139  * \param column [out] if non-NULL, will be set to the column to which the given
0140  * source location points.
0141  *
0142  * \param offset [out] if non-NULL, will be set to the offset into the
0143  * buffer to which the given source location points.
0144  */
0145 CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location,
0146                                                CXFile *file, unsigned *line,
0147                                                unsigned *column,
0148                                                unsigned *offset);
0149
0150 /**
0151  * Retrieve the file, line and column represented by the given source
0152  * location, as specified in a # line directive.
0153  *
0154  * Example: given the following source code in a file somefile.c
0155  *
0156  * \code
0157  * #123 "dummy.c" 1
0158  *
0159  * static int func(void)
0160  * {
0161  *     return 0;
0162  * }
0163  * \endcode
0164  *
0165  * the location information returned by this function would be
0166  *
0167  * File: dummy.c Line: 124 Column: 12
0168  *
0169  * whereas clang_getExpansionLocation would have returned
0170  *
0171  * File: somefile.c Line: 3 Column: 12
0172  *
0173  * \param location the location within a source file that will be decomposed
0174  * into its parts.
0175  *
0176  * \param filename [out] if non-NULL, will be set to the filename of the
0177  * source location. Note that filenames returned will be for "virtual" files,
0178  * which don't necessarily exist on the machine running clang - e.g. when
0179  * parsing preprocessed output obtained from a different environment. If
0180  * a non-NULL value is passed in, remember to dispose of the returned value
0181  * using \c clang_disposeString() once you've finished with it. For an invalid
0182  * source location, an empty string is returned.
0183  *
0184  * \param line [out] if non-NULL, will be set to the line number of the
0185  * source location. For an invalid source location, zero is returned.
0186  *
0187  * \param column [out] if non-NULL, will be set to the column number of the
0188  * source location. For an invalid source location, zero is returned.
0189  */
0190 CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location,
0191                                               CXString *filename,
0192                                               unsigned *line, unsigned *column);
0193
0194 /**
0195  * Legacy API to retrieve the file, line, column, and offset represented
0196  * by the given source location.
0197  *
0198  * This interface has been replaced by the newer interface
0199  * #clang_getExpansionLocation(). See that interface's documentation for
0200  * details.
0201  */
0202 CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location,
0203                                                    CXFile *file, unsigned *line,
0204                                                    unsigned *column,
0205                                                    unsigned *offset);
0206
0207 /**
0208  * Retrieve the file, line, column, and offset represented by
0209  * the given source location.
0210  *
0211  * If the location refers into a macro instantiation, return where the
0212  * location was originally spelled in the source file.
0213  *
0214  * \param location the location within a source file that will be decomposed
0215  * into its parts.
0216  *
0217  * \param file [out] if non-NULL, will be set to the file to which the given
0218  * source location points.
0219  *
0220  * \param line [out] if non-NULL, will be set to the line to which the given
0221  * source location points.
0222  *
0223  * \param column [out] if non-NULL, will be set to the column to which the given
0224  * source location points.
0225  *
0226  * \param offset [out] if non-NULL, will be set to the offset into the
0227  * buffer to which the given source location points.
0228  */
0229 CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location,
0230                                               CXFile *file, unsigned *line,
0231                                               unsigned *column,
0232                                               unsigned *offset);
0233
0234 /**
0235  * Retrieve the file, line, column, and offset represented by
0236  * the given source location.
0237  *
0238  * If the location refers into a macro expansion, return where the macro was
0239  * expanded or where the macro argument was written, if the location points at
0240  * a macro argument.
0241  *
0242  * \param location the location within a source file that will be decomposed
0243  * into its parts.
0244  *
0245  * \param file [out] if non-NULL, will be set to the file to which the given
0246  * source location points.
0247  *
0248  * \param line [out] if non-NULL, will be set to the line to which the given
0249  * source location points.
0250  *
0251  * \param column [out] if non-NULL, will be set to the column to which the given
0252  * source location points.
0253  *
0254  * \param offset [out] if non-NULL, will be set to the offset into the
0255  * buffer to which the given source location points.
0256  */
0257 CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location,
0258                                           CXFile *file, unsigned *line,
0259                                           unsigned *column, unsigned *offset);
0260
0261 /**
0262  * Retrieve a source location representing the first character within a
0263  * source range.
0264  */
0265 CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range);
0266
0267 /**
0268  * Retrieve a source location representing the last character within a
0269  * source range.
0270  */
0271 CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range);
0272
0273 /**
0274  * Identifies an array of ranges.
0275  */
0276 typedef struct {
0277   /** The number of ranges in the \c ranges array. */
0278   unsigned count;
0279   /**
0280    * An array of \c CXSourceRanges.
0281    */
0282   CXSourceRange *ranges;
0283 } CXSourceRangeList;
0284
0285 /**
0286  * Destroy the given \c CXSourceRangeList.
0287  */
0288 CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges);
0289
0290 /**
0291  * @}
0292  */
0293
0294 LLVM_CLANG_C_EXTERN_C_END
0295
0296 #endif