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 380