clang/include/clang-c/CXDiagnostic.h

   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