380 lines · c
1/*===-- clang-c/CXDiagnostic.h - C Index Diagnostics --------------*- 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 diagnostics. *|11|* *|12\*===----------------------------------------------------------------------===*/13 14#ifndef LLVM_CLANG_C_CXDIAGNOSTIC_H15#define LLVM_CLANG_C_CXDIAGNOSTIC_H16 17#include "clang-c/CXSourceLocation.h"18#include "clang-c/CXString.h"19#include "clang-c/ExternC.h"20#include "clang-c/Platform.h"21 22LLVM_CLANG_C_EXTERN_C_BEGIN23 24/**25 * \defgroup CINDEX_DIAG Diagnostic reporting26 *27 * @{28 */29 30/**31 * Describes the severity of a particular diagnostic.32 */33enum CXDiagnosticSeverity {34 /**35 * A diagnostic that has been suppressed, e.g., by a command-line36 * option.37 */38 CXDiagnostic_Ignored = 0,39 40 /**41 * This diagnostic is a note that should be attached to the42 * previous (non-note) diagnostic.43 */44 CXDiagnostic_Note = 1,45 46 /**47 * This diagnostic indicates suspicious code that may not be48 * wrong.49 */50 CXDiagnostic_Warning = 2,51 52 /**53 * This diagnostic indicates that the code is ill-formed.54 */55 CXDiagnostic_Error = 3,56 57 /**58 * This diagnostic indicates that the code is ill-formed such59 * that future parser recovery is unlikely to produce useful60 * results.61 */62 CXDiagnostic_Fatal = 463};64 65/**66 * A single diagnostic, containing the diagnostic's severity,67 * location, text, source ranges, and fix-it hints.68 */69typedef void *CXDiagnostic;70 71/**72 * A group of CXDiagnostics.73 */74typedef void *CXDiagnosticSet;75 76/**77 * Determine the number of diagnostics in a CXDiagnosticSet.78 */79CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);80 81/**82 * Retrieve a diagnostic associated with the given CXDiagnosticSet.83 *84 * \param Diags the CXDiagnosticSet to query.85 * \param Index the zero-based diagnostic number to retrieve.86 *87 * \returns the requested diagnostic. This diagnostic must be freed88 * via a call to \c clang_disposeDiagnostic().89 */90CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,91 unsigned Index);92 93/**94 * Describes the kind of error that occurred (if any) in a call to95 * \c clang_loadDiagnostics.96 */97enum CXLoadDiag_Error {98 /**99 * Indicates that no error occurred.100 */101 CXLoadDiag_None = 0,102 103 /**104 * Indicates that an unknown error occurred while attempting to105 * deserialize diagnostics.106 */107 CXLoadDiag_Unknown = 1,108 109 /**110 * Indicates that the file containing the serialized diagnostics111 * could not be opened.112 */113 CXLoadDiag_CannotLoad = 2,114 115 /**116 * Indicates that the serialized diagnostics file is invalid or117 * corrupt.118 */119 CXLoadDiag_InvalidFile = 3120};121 122/**123 * Deserialize a set of diagnostics from a Clang diagnostics bitcode124 * file.125 *126 * \param file The name of the file to deserialize.127 * \param error A pointer to a enum value recording if there was a problem128 * deserializing the diagnostics.129 * \param errorString A pointer to a CXString for recording the error string130 * if the file was not successfully loaded.131 *132 * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These133 * diagnostics should be released using clang_disposeDiagnosticSet().134 */135CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(136 const char *file, enum CXLoadDiag_Error *error, CXString *errorString);137 138/**139 * Release a CXDiagnosticSet and all of its contained diagnostics.140 */141CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);142 143/**144 * Retrieve the child diagnostics of a CXDiagnostic.145 *146 * This CXDiagnosticSet does not need to be released by147 * clang_disposeDiagnosticSet.148 */149CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);150 151/**152 * Destroy a diagnostic.153 */154CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);155 156/**157 * Options to control the display of diagnostics.158 *159 * The values in this enum are meant to be combined to customize the160 * behavior of \c clang_formatDiagnostic().161 */162enum CXDiagnosticDisplayOptions {163 /**164 * Display the source-location information where the165 * diagnostic was located.166 *167 * When set, diagnostics will be prefixed by the file, line, and168 * (optionally) column to which the diagnostic refers. For example,169 *170 * \code171 * test.c:28: warning: extra tokens at end of #endif directive172 * \endcode173 *174 * This option corresponds to the clang flag \c -fshow-source-location.175 */176 CXDiagnostic_DisplaySourceLocation = 0x01,177 178 /**179 * If displaying the source-location information of the180 * diagnostic, also include the column number.181 *182 * This option corresponds to the clang flag \c -fshow-column.183 */184 CXDiagnostic_DisplayColumn = 0x02,185 186 /**187 * If displaying the source-location information of the188 * diagnostic, also include information about source ranges in a189 * machine-parsable format.190 *191 * This option corresponds to the clang flag192 * \c -fdiagnostics-print-source-range-info.193 */194 CXDiagnostic_DisplaySourceRanges = 0x04,195 196 /**197 * Display the option name associated with this diagnostic, if any.198 *199 * The option name displayed (e.g., -Wconversion) will be placed in brackets200 * after the diagnostic text. This option corresponds to the clang flag201 * \c -fdiagnostics-show-option.202 */203 CXDiagnostic_DisplayOption = 0x08,204 205 /**206 * Display the category number associated with this diagnostic, if any.207 *208 * The category number is displayed within brackets after the diagnostic text.209 * This option corresponds to the clang flag210 * \c -fdiagnostics-show-category=id.211 */212 CXDiagnostic_DisplayCategoryId = 0x10,213 214 /**215 * Display the category name associated with this diagnostic, if any.216 *217 * The category name is displayed within brackets after the diagnostic text.218 * This option corresponds to the clang flag219 * \c -fdiagnostics-show-category=name.220 */221 CXDiagnostic_DisplayCategoryName = 0x20222};223 224/**225 * Format the given diagnostic in a manner that is suitable for display.226 *227 * This routine will format the given diagnostic to a string, rendering228 * the diagnostic according to the various options given. The229 * \c clang_defaultDiagnosticDisplayOptions() function returns the set of230 * options that most closely mimics the behavior of the clang compiler.231 *232 * \param Diagnostic The diagnostic to print.233 *234 * \param Options A set of options that control the diagnostic display,235 * created by combining \c CXDiagnosticDisplayOptions values.236 *237 * \returns A new string containing for formatted diagnostic.238 */239CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,240 unsigned Options);241 242/**243 * Retrieve the set of display options most similar to the244 * default behavior of the clang compiler.245 *246 * \returns A set of display options suitable for use with \c247 * clang_formatDiagnostic().248 */249CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);250 251/**252 * Determine the severity of the given diagnostic.253 */254CINDEX_LINKAGE enum CXDiagnosticSeverity255 clang_getDiagnosticSeverity(CXDiagnostic);256 257/**258 * Retrieve the source location of the given diagnostic.259 *260 * This location is where Clang would print the caret ('^') when261 * displaying the diagnostic on the command line.262 */263CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);264 265/**266 * Retrieve the text of the given diagnostic.267 */268CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);269 270/**271 * Retrieve the name of the command-line option that enabled this272 * diagnostic.273 *274 * \param Diag The diagnostic to be queried.275 *276 * \param Disable If non-NULL, will be set to the option that disables this277 * diagnostic (if any).278 *279 * \returns A string that contains the command-line option used to enable this280 * warning, such as "-Wconversion" or "-pedantic".281 */282CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag,283 CXString *Disable);284 285/**286 * Retrieve the category number for this diagnostic.287 *288 * Diagnostics can be categorized into groups along with other, related289 * diagnostics (e.g., diagnostics under the same warning flag). This routine290 * retrieves the category number for the given diagnostic.291 *292 * \returns The number of the category that contains this diagnostic, or zero293 * if this diagnostic is uncategorized.294 */295CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);296 297/**298 * Retrieve the name of a particular diagnostic category. This299 * is now deprecated. Use clang_getDiagnosticCategoryText()300 * instead.301 *302 * \param Category A diagnostic category number, as returned by303 * \c clang_getDiagnosticCategory().304 *305 * \returns The name of the given diagnostic category.306 */307CINDEX_DEPRECATED CINDEX_LINKAGE CXString308clang_getDiagnosticCategoryName(unsigned Category);309 310/**311 * Retrieve the diagnostic category text for a given diagnostic.312 *313 * \returns The text of the given diagnostic category.314 */315CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic);316 317/**318 * Determine the number of source ranges associated with the given319 * diagnostic.320 */321CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);322 323/**324 * Retrieve a source range associated with the diagnostic.325 *326 * A diagnostic's source ranges highlight important elements in the source327 * code. On the command line, Clang displays source ranges by328 * underlining them with '~' characters.329 *330 * \param Diagnostic the diagnostic whose range is being extracted.331 *332 * \param Range the zero-based index specifying which range to333 *334 * \returns the requested source range.335 */336CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,337 unsigned Range);338 339/**340 * Determine the number of fix-it hints associated with the341 * given diagnostic.342 */343CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);344 345/**346 * Retrieve the replacement information for a given fix-it.347 *348 * Fix-its are described in terms of a source range whose contents349 * should be replaced by a string. This approach generalizes over350 * three kinds of operations: removal of source code (the range covers351 * the code to be removed and the replacement string is empty),352 * replacement of source code (the range covers the code to be353 * replaced and the replacement string provides the new code), and354 * insertion (both the start and end of the range point at the355 * insertion location, and the replacement string provides the text to356 * insert).357 *358 * \param Diagnostic The diagnostic whose fix-its are being queried.359 *360 * \param FixIt The zero-based index of the fix-it.361 *362 * \param ReplacementRange The source range whose contents will be363 * replaced with the returned replacement string. Note that source364 * ranges are half-open ranges [a, b), so the source code should be365 * replaced from a and up to (but not including) b.366 *367 * \returns A string containing text that should be replace the source368 * code indicated by the \c ReplacementRange.369 */370CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(371 CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);372 373/**374 * @}375 */376 377LLVM_CLANG_C_EXTERN_C_END378 379#endif380