| 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_H |
| 15 |
#define LLVM_CLANG_C_CXDIAGNOSTIC_H |
| 16 |
|
| 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 |
|
| 22 |
LLVM_CLANG_C_EXTERN_C_BEGIN |
| 23 |
|
| 24 |
/** |
| 25 |
* \defgroup CINDEX_DIAG Diagnostic reporting |
| 26 |
* |
| 27 |
* @{ |
| 28 |
*/ |
| 29 |
|
| 30 |
/** |
| 31 |
* Describes the severity of a particular diagnostic. |
| 32 |
*/ |
| 33 |
enum CXDiagnosticSeverity { |
| 34 |
/** |
| 35 |
* A diagnostic that has been suppressed, e.g., by a command-line |
| 36 |
* option. |
| 37 |
*/ |
| 38 |
CXDiagnostic_Ignored = 0, |
| 39 |
|
| 40 |
/** |
| 41 |
* This diagnostic is a note that should be attached to the |
| 42 |
* previous (non-note) diagnostic. |
| 43 |
*/ |
| 44 |
CXDiagnostic_Note = 1, |
| 45 |
|
| 46 |
/** |
| 47 |
* This diagnostic indicates suspicious code that may not be |
| 48 |
* 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 such |
| 59 |
* that future parser recovery is unlikely to produce useful |
| 60 |
* results. |
| 61 |
*/ |
| 62 |
CXDiagnostic_Fatal = 4 |
| 63 |
}; |
| 64 |
|
| 65 |
/** |
| 66 |
* A single diagnostic, containing the diagnostic's severity, |
| 67 |
* location, text, source ranges, and fix-it hints. |
| 68 |
*/ |
| 69 |
typedef void *CXDiagnostic; |
| 70 |
|
| 71 |
/** |
| 72 |
* A group of CXDiagnostics. |
| 73 |
*/ |
| 74 |
typedef void *CXDiagnosticSet; |
| 75 |
|
| 76 |
/** |
| 77 |
* Determine the number of diagnostics in a CXDiagnosticSet. |
| 78 |
*/ |
| 79 |
CINDEX_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 freed |
| 88 |
* via a call to \c clang_disposeDiagnostic(). |
| 89 |
*/ |
| 90 |
CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags, |
| 91 |
unsigned Index); |
| 92 |
|
| 93 |
/** |
| 94 |
* Describes the kind of error that occurred (if any) in a call to |
| 95 |
* \c clang_loadDiagnostics. |
| 96 |
*/ |
| 97 |
enum 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 to |
| 105 |
* deserialize diagnostics. |
| 106 |
*/ |
| 107 |
CXLoadDiag_Unknown = 1, |
| 108 |
|
| 109 |
/** |
| 110 |
* Indicates that the file containing the serialized diagnostics |
| 111 |
* could not be opened. |
| 112 |
*/ |
| 113 |
CXLoadDiag_CannotLoad = 2, |
| 114 |
|
| 115 |
/** |
| 116 |
* Indicates that the serialized diagnostics file is invalid or |
| 117 |
* corrupt. |
| 118 |
*/ |
| 119 |
CXLoadDiag_InvalidFile = 3 |
| 120 |
}; |
| 121 |
|
| 122 |
/** |
| 123 |
* Deserialize a set of diagnostics from a Clang diagnostics bitcode |
| 124 |
* 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 problem |
| 128 |
* deserializing the diagnostics. |
| 129 |
* \param errorString A pointer to a CXString for recording the error string |
| 130 |
* if the file was not successfully loaded. |
| 131 |
* |
| 132 |
* \returns A loaded CXDiagnosticSet if successful, and NULL otherwise. These |
| 133 |
* diagnostics should be released using clang_disposeDiagnosticSet(). |
| 134 |
*/ |
| 135 |
CINDEX_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 |
*/ |
| 141 |
CINDEX_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 by |
| 147 |
* clang_disposeDiagnosticSet. |
| 148 |
*/ |
| 149 |
CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D); |
| 150 |
|
| 151 |
/** |
| 152 |
* Destroy a diagnostic. |
| 153 |
*/ |
| 154 |
CINDEX_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 the |
| 160 |
* behavior of \c clang_formatDiagnostic(). |
| 161 |
*/ |
| 162 |
enum CXDiagnosticDisplayOptions { |
| 163 |
/** |
| 164 |
* Display the source-location information where the |
| 165 |
* diagnostic was located. |
| 166 |
* |
| 167 |
* When set, diagnostics will be prefixed by the file, line, and |
| 168 |
* (optionally) column to which the diagnostic refers. For example, |
| 169 |
* |
| 170 |
* \code |
| 171 |
* test.c:28: warning: extra tokens at end of #endif directive |
| 172 |
* \endcode |
| 173 |
* |
| 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 the |
| 180 |
* 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 the |
| 188 |
* diagnostic, also include information about source ranges in a |
| 189 |
* machine-parsable format. |
| 190 |
* |
| 191 |
* This option corresponds to the clang flag |
| 192 |
* \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 brackets |
| 200 |
* after the diagnostic text. This option corresponds to the clang flag |
| 201 |
* \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 flag |
| 210 |
* \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 flag |
| 219 |
* \c -fdiagnostics-show-category=name. |
| 220 |
*/ |
| 221 |
CXDiagnostic_DisplayCategoryName = 0x20 |
| 222 |
}; |
| 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, rendering |
| 228 |
* the diagnostic according to the various options given. The |
| 229 |
* \c clang_defaultDiagnosticDisplayOptions() function returns the set of |
| 230 |
* 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 |
*/ |
| 239 |
CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic, |
| 240 |
unsigned Options); |
| 241 |
|
| 242 |
/** |
| 243 |
* Retrieve the set of display options most similar to the |
| 244 |
* default behavior of the clang compiler. |
| 245 |
* |
| 246 |
* \returns A set of display options suitable for use with \c |
| 247 |
* clang_formatDiagnostic(). |
| 248 |
*/ |
| 249 |
CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void); |
| 250 |
|
| 251 |
/** |
| 252 |
* Determine the severity of the given diagnostic. |
| 253 |
*/ |
| 254 |
CINDEX_LINKAGE enum CXDiagnosticSeverity |
| 255 |
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 ('^') when |
| 261 |
* displaying the diagnostic on the command line. |
| 262 |
*/ |
| 263 |
CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic); |
| 264 |
|
| 265 |
/** |
| 266 |
* Retrieve the text of the given diagnostic. |
| 267 |
*/ |
| 268 |
CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic); |
| 269 |
|
| 270 |
/** |
| 271 |
* Retrieve the name of the command-line option that enabled this |
| 272 |
* 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 this |
| 277 |
* diagnostic (if any). |
| 278 |
* |
| 279 |
* \returns A string that contains the command-line option used to enable this |
| 280 |
* warning, such as "-Wconversion" or "-pedantic". |
| 281 |
*/ |
| 282 |
CINDEX_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, related |
| 289 |
* diagnostics (e.g., diagnostics under the same warning flag). This routine |
| 290 |
* retrieves the category number for the given diagnostic. |
| 291 |
* |
| 292 |
* \returns The number of the category that contains this diagnostic, or zero |
| 293 |
* if this diagnostic is uncategorized. |
| 294 |
*/ |
| 295 |
CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic); |
| 296 |
|
| 297 |
/** |
| 298 |
* Retrieve the name of a particular diagnostic category. This |
| 299 |
* is now deprecated. Use clang_getDiagnosticCategoryText() |
| 300 |
* instead. |
| 301 |
* |
| 302 |
* \param Category A diagnostic category number, as returned by |
| 303 |
* \c clang_getDiagnosticCategory(). |
| 304 |
* |
| 305 |
* \returns The name of the given diagnostic category. |
| 306 |
*/ |
| 307 |
CINDEX_DEPRECATED CINDEX_LINKAGE CXString |
| 308 |
clang_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 |
*/ |
| 315 |
CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic); |
| 316 |
|
| 317 |
/** |
| 318 |
* Determine the number of source ranges associated with the given |
| 319 |
* diagnostic. |
| 320 |
*/ |
| 321 |
CINDEX_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 source |
| 327 |
* code. On the command line, Clang displays source ranges by |
| 328 |
* 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 to |
| 333 |
* |
| 334 |
* \returns the requested source range. |
| 335 |
*/ |
| 336 |
CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic, |
| 337 |
unsigned Range); |
| 338 |
|
| 339 |
/** |
| 340 |
* Determine the number of fix-it hints associated with the |
| 341 |
* given diagnostic. |
| 342 |
*/ |
| 343 |
CINDEX_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 contents |
| 349 |
* should be replaced by a string. This approach generalizes over |
| 350 |
* three kinds of operations: removal of source code (the range covers |
| 351 |
* the code to be removed and the replacement string is empty), |
| 352 |
* replacement of source code (the range covers the code to be |
| 353 |
* replaced and the replacement string provides the new code), and |
| 354 |
* insertion (both the start and end of the range point at the |
| 355 |
* insertion location, and the replacement string provides the text to |
| 356 |
* 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 be |
| 363 |
* replaced with the returned replacement string. Note that source |
| 364 |
* ranges are half-open ranges [a, b), so the source code should be |
| 365 |
* replaced from a and up to (but not including) b. |
| 366 |
* |
| 367 |
* \returns A string containing text that should be replace the source |
| 368 |
* code indicated by the \c ReplacementRange. |
| 369 |
*/ |
| 370 |
CINDEX_LINKAGE CXString clang_getDiagnosticFixIt( |
| 371 |
CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange); |
| 372 |
|
| 373 |
/** |
| 374 |
* @} |
| 375 |
*/ |
| 376 |
|
| 377 |
LLVM_CLANG_C_EXTERN_C_END |
| 378 |
|
| 379 |
#endif |