diff --git a/clang/include/clang-c/CXDiagnostic.h b/clang/include/clang-c/CXDiagnostic.h new file mode 100644 --- /dev/null +++ b/clang/include/clang-c/CXDiagnostic.h @@ -0,0 +1,379 @@ +/*===-- clang-c/CXDiagnostic.h - C Index Diagnostics --------------*- C -*-===*\ +|* *| +|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| +|* Exceptions. *| +|* See https://llvm.org/LICENSE.txt for license information. *| +|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| +|* *| +|*===----------------------------------------------------------------------===*| +|* *| +|* This header provides the interface to C Index diagnostics. *| +|* *| +\*===----------------------------------------------------------------------===*/ + +#ifndef LLVM_CLANG_C_CXDIAGNOSTIC_H +#define LLVM_CLANG_C_CXDIAGNOSTIC_H + +#include "clang-c/CXSourceLocation.h" +#include "clang-c/CXString.h" +#include "clang-c/ExternC.h" +#include "clang-c/Platform.h" + +LLVM_CLANG_C_EXTERN_C_BEGIN + +/** + * \defgroup CINDEX_DIAG Diagnostic reporting + * + * @{ + */ + +/** + * Describes the severity of a particular diagnostic. + */ +enum CXDiagnosticSeverity { + /** + * A diagnostic that has been suppressed, e.g., by a command-line + * option. + */ + CXDiagnostic_Ignored = 0, + + /** + * This diagnostic is a note that should be attached to the + * previous (non-note) diagnostic. + */ + CXDiagnostic_Note = 1, + + /** + * This diagnostic indicates suspicious code that may not be + * wrong. + */ + CXDiagnostic_Warning = 2, + + /** + * This diagnostic indicates that the code is ill-formed. + */ + CXDiagnostic_Error = 3, + + /** + * This diagnostic indicates that the code is ill-formed such + * that future parser recovery is unlikely to produce useful + * results. + */ + CXDiagnostic_Fatal = 4 +}; + +/** + * A single diagnostic, containing the diagnostic's severity, + * location, text, source ranges, and fix-it hints. + */ +typedef void *CXDiagnostic; + +/** + * A group of CXDiagnostics. + */ +typedef void *CXDiagnosticSet; + +/** + * Determine the number of diagnostics in a CXDiagnosticSet. + */ +CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); + +/** + * Retrieve a diagnostic associated with the given CXDiagnosticSet. + * + * \param Diags the CXDiagnosticSet to query. + * \param Index the zero-based diagnostic number to retrieve. + * + * \returns the requested diagnostic. This diagnostic must be freed + * via a call to \c clang_disposeDiagnostic(). + */ +CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, + unsigned Index); + +/** + * Describes the kind of error that occurred (if any) in a call to + * \c clang_loadDiagnostics. + */ +enum CXLoadDiag_Error { + /** + * Indicates that no error occurred. + */ + CXLoadDiag_None = 0, + + /** + * Indicates that an unknown error occurred while attempting to + * deserialize diagnostics. + */ + CXLoadDiag_Unknown = 1, + + /** + * Indicates that the file containing the serialized diagnostics + * could not be opened. + */ + CXLoadDiag_CannotLoad = 2, + + /** + * Indicates that the serialized diagnostics file is invalid or + * corrupt. + */ + CXLoadDiag_InvalidFile = 3 +}; + +/** + * Deserialize a set of diagnostics from a Clang diagnostics bitcode + * file. + * + * \param file The name of the file to deserialize. + * \param error A pointer to a enum value recording if there was a problem + * deserializing the diagnostics. + * \param errorString A pointer to a CXString for recording the error string + * if the file was not successfully loaded. + * + * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These + * diagnostics should be released using clang_disposeDiagnosticSet(). + */ +CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics( + const char *file, enum CXLoadDiag_Error *error, CXString *errorString); + +/** + * Release a CXDiagnosticSet and all of its contained diagnostics. + */ +CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); + +/** + * Retrieve the child diagnostics of a CXDiagnostic. + * + * This CXDiagnosticSet does not need to be released by + * clang_disposeDiagnosticSet. + */ +CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); + +/** + * Destroy a diagnostic. + */ +CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); + +/** + * Options to control the display of diagnostics. + * + * The values in this enum are meant to be combined to customize the + * behavior of \c clang_formatDiagnostic(). + */ +enum CXDiagnosticDisplayOptions { + /** + * Display the source-location information where the + * diagnostic was located. + * + * When set, diagnostics will be prefixed by the file, line, and + * (optionally) column to which the diagnostic refers. For example, + * + * \code + * test.c:28: warning: extra tokens at end of #endif directive + * \endcode + * + * This option corresponds to the clang flag \c -fshow-source-location. + */ + CXDiagnostic_DisplaySourceLocation = 0x01, + + /** + * If displaying the source-location information of the + * diagnostic, also include the column number. + * + * This option corresponds to the clang flag \c -fshow-column. + */ + CXDiagnostic_DisplayColumn = 0x02, + + /** + * If displaying the source-location information of the + * diagnostic, also include information about source ranges in a + * machine-parsable format. + * + * This option corresponds to the clang flag + * \c -fdiagnostics-print-source-range-info. + */ + CXDiagnostic_DisplaySourceRanges = 0x04, + + /** + * Display the option name associated with this diagnostic, if any. + * + * The option name displayed (e.g., -Wconversion) will be placed in brackets + * after the diagnostic text. This option corresponds to the clang flag + * \c -fdiagnostics-show-option. + */ + CXDiagnostic_DisplayOption = 0x08, + + /** + * Display the category number associated with this diagnostic, if any. + * + * The category number is displayed within brackets after the diagnostic text. + * This option corresponds to the clang flag + * \c -fdiagnostics-show-category=id. + */ + CXDiagnostic_DisplayCategoryId = 0x10, + + /** + * Display the category name associated with this diagnostic, if any. + * + * The category name is displayed within brackets after the diagnostic text. + * This option corresponds to the clang flag + * \c -fdiagnostics-show-category=name. + */ + CXDiagnostic_DisplayCategoryName = 0x20 +}; + +/** + * Format the given diagnostic in a manner that is suitable for display. + * + * This routine will format the given diagnostic to a string, rendering + * the diagnostic according to the various options given. The + * \c clang_defaultDiagnosticDisplayOptions() function returns the set of + * options that most closely mimics the behavior of the clang compiler. + * + * \param Diagnostic The diagnostic to print. + * + * \param Options A set of options that control the diagnostic display, + * created by combining \c CXDiagnosticDisplayOptions values. + * + * \returns A new string containing for formatted diagnostic. + */ +CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, + unsigned Options); + +/** + * Retrieve the set of display options most similar to the + * default behavior of the clang compiler. + * + * \returns A set of display options suitable for use with \c + * clang_formatDiagnostic(). + */ +CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); + +/** + * Determine the severity of the given diagnostic. + */ +CINDEX_LINKAGE enum CXDiagnosticSeverity + clang_getDiagnosticSeverity(CXDiagnostic); + +/** + * Retrieve the source location of the given diagnostic. + * + * This location is where Clang would print the caret ('^') when + * displaying the diagnostic on the command line. + */ +CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); + +/** + * Retrieve the text of the given diagnostic. + */ +CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); + +/** + * Retrieve the name of the command-line option that enabled this + * diagnostic. + * + * \param Diag The diagnostic to be queried. + * + * \param Disable If non-NULL, will be set to the option that disables this + * diagnostic (if any). + * + * \returns A string that contains the command-line option used to enable this + * warning, such as "-Wconversion" or "-pedantic". + */ +CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, + CXString *Disable); + +/** + * Retrieve the category number for this diagnostic. + * + * Diagnostics can be categorized into groups along with other, related + * diagnostics (e.g., diagnostics under the same warning flag). This routine + * retrieves the category number for the given diagnostic. + * + * \returns The number of the category that contains this diagnostic, or zero + * if this diagnostic is uncategorized. + */ +CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); + +/** + * Retrieve the name of a particular diagnostic category. This + * is now deprecated. Use clang_getDiagnosticCategoryText() + * instead. + * + * \param Category A diagnostic category number, as returned by + * \c clang_getDiagnosticCategory(). + * + * \returns The name of the given diagnostic category. + */ +CINDEX_DEPRECATED CINDEX_LINKAGE CXString +clang_getDiagnosticCategoryName(unsigned Category); + +/** + * Retrieve the diagnostic category text for a given diagnostic. + * + * \returns The text of the given diagnostic category. + */ +CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); + +/** + * Determine the number of source ranges associated with the given + * diagnostic. + */ +CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); + +/** + * Retrieve a source range associated with the diagnostic. + * + * A diagnostic's source ranges highlight important elements in the source + * code. On the command line, Clang displays source ranges by + * underlining them with '~' characters. + * + * \param Diagnostic the diagnostic whose range is being extracted. + * + * \param Range the zero-based index specifying which range to + * + * \returns the requested source range. + */ +CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, + unsigned Range); + +/** + * Determine the number of fix-it hints associated with the + * given diagnostic. + */ +CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); + +/** + * Retrieve the replacement information for a given fix-it. + * + * Fix-its are described in terms of a source range whose contents + * should be replaced by a string. This approach generalizes over + * three kinds of operations: removal of source code (the range covers + * the code to be removed and the replacement string is empty), + * replacement of source code (the range covers the code to be + * replaced and the replacement string provides the new code), and + * insertion (both the start and end of the range point at the + * insertion location, and the replacement string provides the text to + * insert). + * + * \param Diagnostic The diagnostic whose fix-its are being queried. + * + * \param FixIt The zero-based index of the fix-it. + * + * \param ReplacementRange The source range whose contents will be + * replaced with the returned replacement string. Note that source + * ranges are half-open ranges [a, b), so the source code should be + * replaced from a and up to (but not including) b. + * + * \returns A string containing text that should be replace the source + * code indicated by the \c ReplacementRange. + */ +CINDEX_LINKAGE CXString clang_getDiagnosticFixIt( + CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange); + +/** + * @} + */ + +LLVM_CLANG_C_EXTERN_C_END + +#endif diff --git a/clang/include/clang-c/CXFile.h b/clang/include/clang-c/CXFile.h new file mode 100644 --- /dev/null +++ b/clang/include/clang-c/CXFile.h @@ -0,0 +1,83 @@ +/*===-- clang-c/CXFile.h - C Index File ---------------------------*- C -*-===*\ +|* *| +|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| +|* Exceptions. *| +|* See https://llvm.org/LICENSE.txt for license information. *| +|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| +|* *| +|*===----------------------------------------------------------------------===*| +|* *| +|* This header provides the interface to C Index files. *| +|* *| +\*===----------------------------------------------------------------------===*/ + +#ifndef LLVM_CLANG_C_CXFILE_H +#define LLVM_CLANG_C_CXFILE_H + +#include + +#include "clang-c/CXString.h" +#include "clang-c/ExternC.h" +#include "clang-c/Platform.h" + +LLVM_CLANG_C_EXTERN_C_BEGIN + +/** + * \defgroup CINDEX_FILES File manipulation routines + * + * @{ + */ + +/** + * A particular source file that is part of a translation unit. + */ +typedef void *CXFile; + +/** + * Retrieve the complete file and path name of the given file. + */ +CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); + +/** + * Retrieve the last modification time of the given file. + */ +CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); + +/** + * Uniquely identifies a CXFile, that refers to the same underlying file, + * across an indexing session. + */ +typedef struct { + unsigned long long data[3]; +} CXFileUniqueID; + +/** + * Retrieve the unique ID for the given \c file. + * + * \param file the file to get the ID for. + * \param outID stores the returned CXFileUniqueID. + * \returns If there was a failure getting the unique ID, returns non-zero, + * otherwise returns 0. + */ +CINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID); + +/** + * Returns non-zero if the \c file1 and \c file2 point to the same file, + * or they are both NULL. + */ +CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2); + +/** + * Returns the real path name of \c file. + * + * An empty string may be returned. Use \c clang_getFileName() in that case. + */ +CINDEX_LINKAGE CXString clang_File_tryGetRealPathName(CXFile file); + +/** + * @} + */ + +LLVM_CLANG_C_EXTERN_C_END + +#endif diff --git a/clang/include/clang-c/CXSourceLocation.h b/clang/include/clang-c/CXSourceLocation.h new file mode 100644 --- /dev/null +++ b/clang/include/clang-c/CXSourceLocation.h @@ -0,0 +1,286 @@ +/*===-- clang-c/CXSourceLocation.h - C Index Source Location ------*- C -*-===*\ +|* *| +|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *| +|* Exceptions. *| +|* See https://llvm.org/LICENSE.txt for license information. *| +|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *| +|* *| +|*===----------------------------------------------------------------------===*| +|* *| +|* This header provides the interface to C Index source locations. *| +|* *| +\*===----------------------------------------------------------------------===*/ + +#ifndef LLVM_CLANG_C_CXSOURCE_LOCATION_H +#define LLVM_CLANG_C_CXSOURCE_LOCATION_H + +#include "clang-c/CXFile.h" +#include "clang-c/CXString.h" +#include "clang-c/ExternC.h" +#include "clang-c/Platform.h" + +LLVM_CLANG_C_EXTERN_C_BEGIN + +/** + * \defgroup CINDEX_LOCATIONS Physical source locations + * + * Clang represents physical source locations in its abstract syntax tree in + * great detail, with file, line, and column information for the majority of + * the tokens parsed in the source code. These data types and functions are + * used to represent source location information, either for a particular + * point in the program or for a range of points in the program, and extract + * specific location information from those data types. + * + * @{ + */ + +/** + * Identifies a specific source location within a translation + * unit. + * + * Use clang_getExpansionLocation() or clang_getSpellingLocation() + * to map a source location to a particular file, line, and column. + */ +typedef struct { + const void *ptr_data[2]; + unsigned int_data; +} CXSourceLocation; + +/** + * Identifies a half-open character range in the source code. + * + * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the + * starting and end locations from a source range, respectively. + */ +typedef struct { + const void *ptr_data[2]; + unsigned begin_int_data; + unsigned end_int_data; +} CXSourceRange; + +/** + * Retrieve a NULL (invalid) source location. + */ +CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); + +/** + * Determine whether two source locations, which must refer into + * the same translation unit, refer to exactly the same point in the source + * code. + * + * \returns non-zero if the source locations refer to the same location, zero + * if they refer to different locations. + */ +CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, + CXSourceLocation loc2); + +/** + * Returns non-zero if the given source location is in a system header. + */ +CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); + +/** + * Returns non-zero if the given source location is in the main file of + * the corresponding translation unit. + */ +CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); + +/** + * Retrieve a NULL (invalid) source range. + */ +CINDEX_LINKAGE CXSourceRange clang_getNullRange(void); + +/** + * Retrieve a source range given the beginning and ending source + * locations. + */ +CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, + CXSourceLocation end); + +/** + * Determine whether two ranges are equivalent. + * + * \returns non-zero if the ranges are the same, zero if they differ. + */ +CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, + CXSourceRange range2); + +/** + * Returns non-zero if \p range is null. + */ +CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); + +/** + * Retrieve the file, line, column, and offset represented by + * the given source location. + * + * If the location refers into a macro expansion, retrieves the + * location of the macro expansion. + * + * \param location the location within a source file that will be decomposed + * into its parts. + * + * \param file [out] if non-NULL, will be set to the file to which the given + * source location points. + * + * \param line [out] if non-NULL, will be set to the line to which the given + * source location points. + * + * \param column [out] if non-NULL, will be set to the column to which the given + * source location points. + * + * \param offset [out] if non-NULL, will be set to the offset into the + * buffer to which the given source location points. + */ +CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, + CXFile *file, unsigned *line, + unsigned *column, + unsigned *offset); + +/** + * Retrieve the file, line and column represented by the given source + * location, as specified in a # line directive. + * + * Example: given the following source code in a file somefile.c + * + * \code + * #123 "dummy.c" 1 + * + * static int func(void) + * { + * return 0; + * } + * \endcode + * + * the location information returned by this function would be + * + * File: dummy.c Line: 124 Column: 12 + * + * whereas clang_getExpansionLocation would have returned + * + * File: somefile.c Line: 3 Column: 12 + * + * \param location the location within a source file that will be decomposed + * into its parts. + * + * \param filename [out] if non-NULL, will be set to the filename of the + * source location. Note that filenames returned will be for "virtual" files, + * which don't necessarily exist on the machine running clang - e.g. when + * parsing preprocessed output obtained from a different environment. If + * a non-NULL value is passed in, remember to dispose of the returned value + * using \c clang_disposeString() once you've finished with it. For an invalid + * source location, an empty string is returned. + * + * \param line [out] if non-NULL, will be set to the line number of the + * source location. For an invalid source location, zero is returned. + * + * \param column [out] if non-NULL, will be set to the column number of the + * source location. For an invalid source location, zero is returned. + */ +CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, + CXString *filename, + unsigned *line, unsigned *column); + +/** + * Legacy API to retrieve the file, line, column, and offset represented + * by the given source location. + * + * This interface has been replaced by the newer interface + * #clang_getExpansionLocation(). See that interface's documentation for + * details. + */ +CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, + CXFile *file, unsigned *line, + unsigned *column, + unsigned *offset); + +/** + * Retrieve the file, line, column, and offset represented by + * the given source location. + * + * If the location refers into a macro instantiation, return where the + * location was originally spelled in the source file. + * + * \param location the location within a source file that will be decomposed + * into its parts. + * + * \param file [out] if non-NULL, will be set to the file to which the given + * source location points. + * + * \param line [out] if non-NULL, will be set to the line to which the given + * source location points. + * + * \param column [out] if non-NULL, will be set to the column to which the given + * source location points. + * + * \param offset [out] if non-NULL, will be set to the offset into the + * buffer to which the given source location points. + */ +CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, + CXFile *file, unsigned *line, + unsigned *column, + unsigned *offset); + +/** + * Retrieve the file, line, column, and offset represented by + * the given source location. + * + * If the location refers into a macro expansion, return where the macro was + * expanded or where the macro argument was written, if the location points at + * a macro argument. + * + * \param location the location within a source file that will be decomposed + * into its parts. + * + * \param file [out] if non-NULL, will be set to the file to which the given + * source location points. + * + * \param line [out] if non-NULL, will be set to the line to which the given + * source location points. + * + * \param column [out] if non-NULL, will be set to the column to which the given + * source location points. + * + * \param offset [out] if non-NULL, will be set to the offset into the + * buffer to which the given source location points. + */ +CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, + CXFile *file, unsigned *line, + unsigned *column, unsigned *offset); + +/** + * Retrieve a source location representing the first character within a + * source range. + */ +CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); + +/** + * Retrieve a source location representing the last character within a + * source range. + */ +CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); + +/** + * Identifies an array of ranges. + */ +typedef struct { + /** The number of ranges in the \c ranges array. */ + unsigned count; + /** + * An array of \c CXSourceRanges. + */ + CXSourceRange *ranges; +} CXSourceRangeList; + +/** + * Destroy the given \c CXSourceRangeList. + */ +CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); + +/** + * @} + */ + +LLVM_CLANG_C_EXTERN_C_END + +#endif diff --git a/clang/include/clang-c/Index.h b/clang/include/clang-c/Index.h --- a/clang/include/clang-c/Index.h +++ b/clang/include/clang-c/Index.h @@ -16,10 +16,11 @@ #ifndef LLVM_CLANG_C_INDEX_H #define LLVM_CLANG_C_INDEX_H -#include - #include "clang-c/BuildSystem.h" +#include "clang-c/CXDiagnostic.h" #include "clang-c/CXErrorCode.h" +#include "clang-c/CXFile.h" +#include "clang-c/CXSourceLocation.h" #include "clang-c/CXString.h" #include "clang-c/ExternC.h" #include "clang-c/Platform.h" @@ -341,45 +342,6 @@ CINDEX_LINKAGE void clang_CXIndex_setInvocationEmissionPathOption(CXIndex, const char *Path); -/** - * \defgroup CINDEX_FILES File manipulation routines - * - * @{ - */ - -/** - * A particular source file that is part of a translation unit. - */ -typedef void *CXFile; - -/** - * Retrieve the complete file and path name of the given file. - */ -CINDEX_LINKAGE CXString clang_getFileName(CXFile SFile); - -/** - * Retrieve the last modification time of the given file. - */ -CINDEX_LINKAGE time_t clang_getFileTime(CXFile SFile); - -/** - * Uniquely identifies a CXFile, that refers to the same underlying file, - * across an indexing session. - */ -typedef struct { - unsigned long long data[3]; -} CXFileUniqueID; - -/** - * Retrieve the unique ID for the given \c file. - * - * \param file the file to get the ID for. - * \param outID stores the returned CXFileUniqueID. - * \returns If there was a failure getting the unique ID, returns non-zero, - * otherwise returns 0. - */ -CINDEX_LINKAGE int clang_getFileUniqueID(CXFile file, CXFileUniqueID *outID); - /** * Determine whether the given header is guarded against * multiple inclusions, either with the conventional @@ -416,76 +378,6 @@ CINDEX_LINKAGE const char *clang_getFileContents(CXTranslationUnit tu, CXFile file, size_t *size); -/** - * Returns non-zero if the \c file1 and \c file2 point to the same file, - * or they are both NULL. - */ -CINDEX_LINKAGE int clang_File_isEqual(CXFile file1, CXFile file2); - -/** - * Returns the real path name of \c file. - * - * An empty string may be returned. Use \c clang_getFileName() in that case. - */ -CINDEX_LINKAGE CXString clang_File_tryGetRealPathName(CXFile file); - -/** - * @} - */ - -/** - * \defgroup CINDEX_LOCATIONS Physical source locations - * - * Clang represents physical source locations in its abstract syntax tree in - * great detail, with file, line, and column information for the majority of - * the tokens parsed in the source code. These data types and functions are - * used to represent source location information, either for a particular - * point in the program or for a range of points in the program, and extract - * specific location information from those data types. - * - * @{ - */ - -/** - * Identifies a specific source location within a translation - * unit. - * - * Use clang_getExpansionLocation() or clang_getSpellingLocation() - * to map a source location to a particular file, line, and column. - */ -typedef struct { - const void *ptr_data[2]; - unsigned int_data; -} CXSourceLocation; - -/** - * Identifies a half-open character range in the source code. - * - * Use clang_getRangeStart() and clang_getRangeEnd() to retrieve the - * starting and end locations from a source range, respectively. - */ -typedef struct { - const void *ptr_data[2]; - unsigned begin_int_data; - unsigned end_int_data; -} CXSourceRange; - -/** - * Retrieve a NULL (invalid) source location. - */ -CINDEX_LINKAGE CXSourceLocation clang_getNullLocation(void); - -/** - * Determine whether two source locations, which must refer into - * the same translation unit, refer to exactly the same point in the source - * code. - * - * \returns non-zero if the source locations refer to the same location, zero - * if they refer to different locations. - */ -CINDEX_LINKAGE unsigned clang_equalLocations(CXSourceLocation loc1, - CXSourceLocation loc2); - /** * Retrieves the source location associated with a given file/line/column * in a particular translation unit. @@ -501,204 +393,6 @@ CXFile file, unsigned offset); -/** - * Returns non-zero if the given source location is in a system header. - */ -CINDEX_LINKAGE int clang_Location_isInSystemHeader(CXSourceLocation location); - -/** - * Returns non-zero if the given source location is in the main file of - * the corresponding translation unit. - */ -CINDEX_LINKAGE int clang_Location_isFromMainFile(CXSourceLocation location); - -/** - * Retrieve a NULL (invalid) source range. - */ -CINDEX_LINKAGE CXSourceRange clang_getNullRange(void); - -/** - * Retrieve a source range given the beginning and ending source - * locations. - */ -CINDEX_LINKAGE CXSourceRange clang_getRange(CXSourceLocation begin, - CXSourceLocation end); - -/** - * Determine whether two ranges are equivalent. - * - * \returns non-zero if the ranges are the same, zero if they differ. - */ -CINDEX_LINKAGE unsigned clang_equalRanges(CXSourceRange range1, - CXSourceRange range2); - -/** - * Returns non-zero if \p range is null. - */ -CINDEX_LINKAGE int clang_Range_isNull(CXSourceRange range); - -/** - * Retrieve the file, line, column, and offset represented by - * the given source location. - * - * If the location refers into a macro expansion, retrieves the - * location of the macro expansion. - * - * \param location the location within a source file that will be decomposed - * into its parts. - * - * \param file [out] if non-NULL, will be set to the file to which the given - * source location points. - * - * \param line [out] if non-NULL, will be set to the line to which the given - * source location points. - * - * \param column [out] if non-NULL, will be set to the column to which the given - * source location points. - * - * \param offset [out] if non-NULL, will be set to the offset into the - * buffer to which the given source location points. - */ -CINDEX_LINKAGE void clang_getExpansionLocation(CXSourceLocation location, - CXFile *file, unsigned *line, - unsigned *column, - unsigned *offset); - -/** - * Retrieve the file, line and column represented by the given source - * location, as specified in a # line directive. - * - * Example: given the following source code in a file somefile.c - * - * \code - * #123 "dummy.c" 1 - * - * static int func(void) - * { - * return 0; - * } - * \endcode - * - * the location information returned by this function would be - * - * File: dummy.c Line: 124 Column: 12 - * - * whereas clang_getExpansionLocation would have returned - * - * File: somefile.c Line: 3 Column: 12 - * - * \param location the location within a source file that will be decomposed - * into its parts. - * - * \param filename [out] if non-NULL, will be set to the filename of the - * source location. Note that filenames returned will be for "virtual" files, - * which don't necessarily exist on the machine running clang - e.g. when - * parsing preprocessed output obtained from a different environment. If - * a non-NULL value is passed in, remember to dispose of the returned value - * using \c clang_disposeString() once you've finished with it. For an invalid - * source location, an empty string is returned. - * - * \param line [out] if non-NULL, will be set to the line number of the - * source location. For an invalid source location, zero is returned. - * - * \param column [out] if non-NULL, will be set to the column number of the - * source location. For an invalid source location, zero is returned. - */ -CINDEX_LINKAGE void clang_getPresumedLocation(CXSourceLocation location, - CXString *filename, - unsigned *line, unsigned *column); - -/** - * Legacy API to retrieve the file, line, column, and offset represented - * by the given source location. - * - * This interface has been replaced by the newer interface - * #clang_getExpansionLocation(). See that interface's documentation for - * details. - */ -CINDEX_LINKAGE void clang_getInstantiationLocation(CXSourceLocation location, - CXFile *file, unsigned *line, - unsigned *column, - unsigned *offset); - -/** - * Retrieve the file, line, column, and offset represented by - * the given source location. - * - * If the location refers into a macro instantiation, return where the - * location was originally spelled in the source file. - * - * \param location the location within a source file that will be decomposed - * into its parts. - * - * \param file [out] if non-NULL, will be set to the file to which the given - * source location points. - * - * \param line [out] if non-NULL, will be set to the line to which the given - * source location points. - * - * \param column [out] if non-NULL, will be set to the column to which the given - * source location points. - * - * \param offset [out] if non-NULL, will be set to the offset into the - * buffer to which the given source location points. - */ -CINDEX_LINKAGE void clang_getSpellingLocation(CXSourceLocation location, - CXFile *file, unsigned *line, - unsigned *column, - unsigned *offset); - -/** - * Retrieve the file, line, column, and offset represented by - * the given source location. - * - * If the location refers into a macro expansion, return where the macro was - * expanded or where the macro argument was written, if the location points at - * a macro argument. - * - * \param location the location within a source file that will be decomposed - * into its parts. - * - * \param file [out] if non-NULL, will be set to the file to which the given - * source location points. - * - * \param line [out] if non-NULL, will be set to the line to which the given - * source location points. - * - * \param column [out] if non-NULL, will be set to the column to which the given - * source location points. - * - * \param offset [out] if non-NULL, will be set to the offset into the - * buffer to which the given source location points. - */ -CINDEX_LINKAGE void clang_getFileLocation(CXSourceLocation location, - CXFile *file, unsigned *line, - unsigned *column, unsigned *offset); - -/** - * Retrieve a source location representing the first character within a - * source range. - */ -CINDEX_LINKAGE CXSourceLocation clang_getRangeStart(CXSourceRange range); - -/** - * Retrieve a source location representing the last character within a - * source range. - */ -CINDEX_LINKAGE CXSourceLocation clang_getRangeEnd(CXSourceRange range); - -/** - * Identifies an array of ranges. - */ -typedef struct { - /** The number of ranges in the \c ranges array. */ - unsigned count; - /** - * An array of \c CXSourceRanges. - */ - CXSourceRange *ranges; -} CXSourceRangeList; - /** * Retrieve all ranges that were skipped by the preprocessor. * @@ -718,142 +412,6 @@ CINDEX_LINKAGE CXSourceRangeList * clang_getAllSkippedRanges(CXTranslationUnit tu); -/** - * Destroy the given \c CXSourceRangeList. - */ -CINDEX_LINKAGE void clang_disposeSourceRangeList(CXSourceRangeList *ranges); - -/** - * @} - */ - -/** - * \defgroup CINDEX_DIAG Diagnostic reporting - * - * @{ - */ - -/** - * Describes the severity of a particular diagnostic. - */ -enum CXDiagnosticSeverity { - /** - * A diagnostic that has been suppressed, e.g., by a command-line - * option. - */ - CXDiagnostic_Ignored = 0, - - /** - * This diagnostic is a note that should be attached to the - * previous (non-note) diagnostic. - */ - CXDiagnostic_Note = 1, - - /** - * This diagnostic indicates suspicious code that may not be - * wrong. - */ - CXDiagnostic_Warning = 2, - - /** - * This diagnostic indicates that the code is ill-formed. - */ - CXDiagnostic_Error = 3, - - /** - * This diagnostic indicates that the code is ill-formed such - * that future parser recovery is unlikely to produce useful - * results. - */ - CXDiagnostic_Fatal = 4 -}; - -/** - * A single diagnostic, containing the diagnostic's severity, - * location, text, source ranges, and fix-it hints. - */ -typedef void *CXDiagnostic; - -/** - * A group of CXDiagnostics. - */ -typedef void *CXDiagnosticSet; - -/** - * Determine the number of diagnostics in a CXDiagnosticSet. - */ -CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags); - -/** - * Retrieve a diagnostic associated with the given CXDiagnosticSet. - * - * \param Diags the CXDiagnosticSet to query. - * \param Index the zero-based diagnostic number to retrieve. - * - * \returns the requested diagnostic. This diagnostic must be freed - * via a call to \c clang_disposeDiagnostic(). - */ -CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, - unsigned Index); - -/** - * Describes the kind of error that occurred (if any) in a call to - * \c clang_loadDiagnostics. - */ -enum CXLoadDiag_Error { - /** - * Indicates that no error occurred. - */ - CXLoadDiag_None = 0, - - /** - * Indicates that an unknown error occurred while attempting to - * deserialize diagnostics. - */ - CXLoadDiag_Unknown = 1, - - /** - * Indicates that the file containing the serialized diagnostics - * could not be opened. - */ - CXLoadDiag_CannotLoad = 2, - - /** - * Indicates that the serialized diagnostics file is invalid or - * corrupt. - */ - CXLoadDiag_InvalidFile = 3 -}; - -/** - * Deserialize a set of diagnostics from a Clang diagnostics bitcode - * file. - * - * \param file The name of the file to deserialize. - * \param error A pointer to a enum value recording if there was a problem - * deserializing the diagnostics. - * \param errorString A pointer to a CXString for recording the error string - * if the file was not successfully loaded. - * - * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These - * diagnostics should be released using clang_disposeDiagnosticSet(). - */ -CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics( - const char *file, enum CXLoadDiag_Error *error, CXString *errorString); - -/** - * Release a CXDiagnosticSet and all of its contained diagnostics. - */ -CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags); - -/** - * Retrieve the child diagnostics of a CXDiagnostic. - * - * This CXDiagnosticSet does not need to be released by - * clang_disposeDiagnosticSet. - */ -CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); - /** * Determine the number of diagnostics produced for the given * translation unit. @@ -881,232 +439,6 @@ CINDEX_LINKAGE CXDiagnosticSet clang_getDiagnosticSetFromTU(CXTranslationUnit Unit); -/** - * Destroy a diagnostic. - */ -CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic); - -/** - * Options to control the display of diagnostics. - * - * The values in this enum are meant to be combined to customize the - * behavior of \c clang_formatDiagnostic(). - */ -enum CXDiagnosticDisplayOptions { - /** - * Display the source-location information where the - * diagnostic was located. - * - * When set, diagnostics will be prefixed by the file, line, and - * (optionally) column to which the diagnostic refers. For example, - * - * \code - * test.c:28: warning: extra tokens at end of #endif directive - * \endcode - * - * This option corresponds to the clang flag \c -fshow-source-location. - */ - CXDiagnostic_DisplaySourceLocation = 0x01, - - /** - * If displaying the source-location information of the - * diagnostic, also include the column number. - * - * This option corresponds to the clang flag \c -fshow-column. - */ - CXDiagnostic_DisplayColumn = 0x02, - - /** - * If displaying the source-location information of the - * diagnostic, also include information about source ranges in a - * machine-parsable format. - * - * This option corresponds to the clang flag - * \c -fdiagnostics-print-source-range-info. - */ - CXDiagnostic_DisplaySourceRanges = 0x04, - - /** - * Display the option name associated with this diagnostic, if any. - * - * The option name displayed (e.g., -Wconversion) will be placed in brackets - * after the diagnostic text. This option corresponds to the clang flag - * \c -fdiagnostics-show-option. - */ - CXDiagnostic_DisplayOption = 0x08, - - /** - * Display the category number associated with this diagnostic, if any. - * - * The category number is displayed within brackets after the diagnostic text. - * This option corresponds to the clang flag - * \c -fdiagnostics-show-category=id. - */ - CXDiagnostic_DisplayCategoryId = 0x10, - - /** - * Display the category name associated with this diagnostic, if any. - * - * The category name is displayed within brackets after the diagnostic text. - * This option corresponds to the clang flag - * \c -fdiagnostics-show-category=name. - */ - CXDiagnostic_DisplayCategoryName = 0x20 -}; - -/** - * Format the given diagnostic in a manner that is suitable for display. - * - * This routine will format the given diagnostic to a string, rendering - * the diagnostic according to the various options given. The - * \c clang_defaultDiagnosticDisplayOptions() function returns the set of - * options that most closely mimics the behavior of the clang compiler. - * - * \param Diagnostic The diagnostic to print. - * - * \param Options A set of options that control the diagnostic display, - * created by combining \c CXDiagnosticDisplayOptions values. - * - * \returns A new string containing for formatted diagnostic. - */ -CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, - unsigned Options); - -/** - * Retrieve the set of display options most similar to the - * default behavior of the clang compiler. - * - * \returns A set of display options suitable for use with \c - * clang_formatDiagnostic(). - */ -CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); - -/** - * Determine the severity of the given diagnostic. - */ -CINDEX_LINKAGE enum CXDiagnosticSeverity - clang_getDiagnosticSeverity(CXDiagnostic); - -/** - * Retrieve the source location of the given diagnostic. - * - * This location is where Clang would print the caret ('^') when - * displaying the diagnostic on the command line. - */ -CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); - -/** - * Retrieve the text of the given diagnostic. - */ -CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); - -/** - * Retrieve the name of the command-line option that enabled this - * diagnostic. - * - * \param Diag The diagnostic to be queried. - * - * \param Disable If non-NULL, will be set to the option that disables this - * diagnostic (if any). - * - * \returns A string that contains the command-line option used to enable this - * warning, such as "-Wconversion" or "-pedantic". - */ -CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag, - CXString *Disable); - -/** - * Retrieve the category number for this diagnostic. - * - * Diagnostics can be categorized into groups along with other, related - * diagnostics (e.g., diagnostics under the same warning flag). This routine - * retrieves the category number for the given diagnostic. - * - * \returns The number of the category that contains this diagnostic, or zero - * if this diagnostic is uncategorized. - */ -CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); - -/** - * Retrieve the name of a particular diagnostic category. This - * is now deprecated. Use clang_getDiagnosticCategoryText() - * instead. - * - * \param Category A diagnostic category number, as returned by - * \c clang_getDiagnosticCategory(). - * - * \returns The name of the given diagnostic category. - */ -CINDEX_DEPRECATED CINDEX_LINKAGE CXString -clang_getDiagnosticCategoryName(unsigned Category); - -/** - * Retrieve the diagnostic category text for a given diagnostic. - * - * \returns The text of the given diagnostic category. - */ -CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); - -/** - * Determine the number of source ranges associated with the given - * diagnostic. - */ -CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic); - -/** - * Retrieve a source range associated with the diagnostic. - * - * A diagnostic's source ranges highlight important elements in the source - * code. On the command line, Clang displays source ranges by - * underlining them with '~' characters. - * - * \param Diagnostic the diagnostic whose range is being extracted. - * - * \param Range the zero-based index specifying which range to - * - * \returns the requested source range. - */ -CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, - unsigned Range); - -/** - * Determine the number of fix-it hints associated with the - * given diagnostic. - */ -CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic); - -/** - * Retrieve the replacement information for a given fix-it. - * - * Fix-its are described in terms of a source range whose contents - * should be replaced by a string. This approach generalizes over - * three kinds of operations: removal of source code (the range covers - * the code to be removed and the replacement string is empty), - * replacement of source code (the range covers the code to be - * replaced and the replacement string provides the new code), and - * insertion (both the start and end of the range point at the - * insertion location, and the replacement string provides the text to - * insert). - * - * \param Diagnostic The diagnostic whose fix-its are being queried. - * - * \param FixIt The zero-based index of the fix-it. - * - * \param ReplacementRange The source range whose contents will be - * replaced with the returned replacement string. Note that source - * ranges are half-open ranges [a, b), so the source code should be - * replaced from a and up to (but not including) b. - * - * \returns A string containing text that should be replace the source - * code indicated by the \c ReplacementRange. - */ -CINDEX_LINKAGE CXString clang_getDiagnosticFixIt( - CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange); - -/** - * @} - */ - /** * \defgroup CINDEX_TRANSLATION_UNIT Translation unit manipulation *