/*===-- 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 single diagnostic, containing the diagnostic's severity, * location, text, source ranges, and fix-it hints. */ CXDiagnostic; /** * A group of CXDiagnostics. */ 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 { … }; /** * 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 { … }; /** * 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
Codebase Browser
llvm