include/clang-c/CXDiagnostic.h

0001 /*===-- clang-c/CXDiagnostic.h - C Index Diagnostics --------------*- C -*-===*\
0002 |*                                                                            *|
0003 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
0004 |* Exceptions.                                                                *|
0005 |* See https://llvm.org/LICENSE.txt for license information.                  *|
0006 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
0007 |*                                                                            *|
0008 |*===----------------------------------------------------------------------===*|
0009 |*                                                                            *|
0010 |* This header provides the interface to C Index diagnostics.                 *|
0011 |*                                                                            *|
0012 \*===----------------------------------------------------------------------===*/
0013
0014 #ifndef LLVM_CLANG_C_CXDIAGNOSTIC_H
0015 #define LLVM_CLANG_C_CXDIAGNOSTIC_H
0016
0017 #include "clang-c/CXSourceLocation.h"
0018 #include "clang-c/CXString.h"
0019 #include "clang-c/ExternC.h"
0020 #include "clang-c/Platform.h"
0021
0022 LLVM_CLANG_C_EXTERN_C_BEGIN
0023
0024 /**
0025  * \defgroup CINDEX_DIAG Diagnostic reporting
0026  *
0027  * @{
0028  */
0029
0030 /**
0031  * Describes the severity of a particular diagnostic.
0032  */
0033 enum CXDiagnosticSeverity {
0034   /**
0035    * A diagnostic that has been suppressed, e.g., by a command-line
0036    * option.
0037    */
0038   CXDiagnostic_Ignored = 0,
0039
0040   /**
0041    * This diagnostic is a note that should be attached to the
0042    * previous (non-note) diagnostic.
0043    */
0044   CXDiagnostic_Note = 1,
0045
0046   /**
0047    * This diagnostic indicates suspicious code that may not be
0048    * wrong.
0049    */
0050   CXDiagnostic_Warning = 2,
0051
0052   /**
0053    * This diagnostic indicates that the code is ill-formed.
0054    */
0055   CXDiagnostic_Error = 3,
0056
0057   /**
0058    * This diagnostic indicates that the code is ill-formed such
0059    * that future parser recovery is unlikely to produce useful
0060    * results.
0061    */
0062   CXDiagnostic_Fatal = 4
0063 };
0064
0065 /**
0066  * A single diagnostic, containing the diagnostic's severity,
0067  * location, text, source ranges, and fix-it hints.
0068  */
0069 typedef void *CXDiagnostic;
0070
0071 /**
0072  * A group of CXDiagnostics.
0073  */
0074 typedef void *CXDiagnosticSet;
0075
0076 /**
0077  * Determine the number of diagnostics in a CXDiagnosticSet.
0078  */
0079 CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet(CXDiagnosticSet Diags);
0080
0081 /**
0082  * Retrieve a diagnostic associated with the given CXDiagnosticSet.
0083  *
0084  * \param Diags the CXDiagnosticSet to query.
0085  * \param Index the zero-based diagnostic number to retrieve.
0086  *
0087  * \returns the requested diagnostic. This diagnostic must be freed
0088  * via a call to \c clang_disposeDiagnostic().
0089  */
0090 CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet(CXDiagnosticSet Diags,
0091                                                      unsigned Index);
0092
0093 /**
0094  * Describes the kind of error that occurred (if any) in a call to
0095  * \c clang_loadDiagnostics.
0096  */
0097 enum CXLoadDiag_Error {
0098   /**
0099    * Indicates that no error occurred.
0100    */
0101   CXLoadDiag_None = 0,
0102
0103   /**
0104    * Indicates that an unknown error occurred while attempting to
0105    * deserialize diagnostics.
0106    */
0107   CXLoadDiag_Unknown = 1,
0108
0109   /**
0110    * Indicates that the file containing the serialized diagnostics
0111    * could not be opened.
0112    */
0113   CXLoadDiag_CannotLoad = 2,
0114
0115   /**
0116    * Indicates that the serialized diagnostics file is invalid or
0117    * corrupt.
0118    */
0119   CXLoadDiag_InvalidFile = 3
0120 };
0121
0122 /**
0123  * Deserialize a set of diagnostics from a Clang diagnostics bitcode
0124  * file.
0125  *
0126  * \param file The name of the file to deserialize.
0127  * \param error A pointer to a enum value recording if there was a problem
0128  *        deserializing the diagnostics.
0129  * \param errorString A pointer to a CXString for recording the error string
0130  *        if the file was not successfully loaded.
0131  *
0132  * \returns A loaded CXDiagnosticSet if successful, and NULL otherwise.  These
0133  * diagnostics should be released using clang_disposeDiagnosticSet().
0134  */
0135 CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics(
0136     const char *file, enum CXLoadDiag_Error *error, CXString *errorString);
0137
0138 /**
0139  * Release a CXDiagnosticSet and all of its contained diagnostics.
0140  */
0141 CINDEX_LINKAGE void clang_disposeDiagnosticSet(CXDiagnosticSet Diags);
0142
0143 /**
0144  * Retrieve the child diagnostics of a CXDiagnostic.
0145  *
0146  * This CXDiagnosticSet does not need to be released by
0147  * clang_disposeDiagnosticSet.
0148  */
0149 CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics(CXDiagnostic D);
0150
0151 /**
0152  * Destroy a diagnostic.
0153  */
0154 CINDEX_LINKAGE void clang_disposeDiagnostic(CXDiagnostic Diagnostic);
0155
0156 /**
0157  * Options to control the display of diagnostics.
0158  *
0159  * The values in this enum are meant to be combined to customize the
0160  * behavior of \c clang_formatDiagnostic().
0161  */
0162 enum CXDiagnosticDisplayOptions {
0163   /**
0164    * Display the source-location information where the
0165    * diagnostic was located.
0166    *
0167    * When set, diagnostics will be prefixed by the file, line, and
0168    * (optionally) column to which the diagnostic refers. For example,
0169    *
0170    * \code
0171    * test.c:28: warning: extra tokens at end of #endif directive
0172    * \endcode
0173    *
0174    * This option corresponds to the clang flag \c -fshow-source-location.
0175    */
0176   CXDiagnostic_DisplaySourceLocation = 0x01,
0177
0178   /**
0179    * If displaying the source-location information of the
0180    * diagnostic, also include the column number.
0181    *
0182    * This option corresponds to the clang flag \c -fshow-column.
0183    */
0184   CXDiagnostic_DisplayColumn = 0x02,
0185
0186   /**
0187    * If displaying the source-location information of the
0188    * diagnostic, also include information about source ranges in a
0189    * machine-parsable format.
0190    *
0191    * This option corresponds to the clang flag
0192    * \c -fdiagnostics-print-source-range-info.
0193    */
0194   CXDiagnostic_DisplaySourceRanges = 0x04,
0195
0196   /**
0197    * Display the option name associated with this diagnostic, if any.
0198    *
0199    * The option name displayed (e.g., -Wconversion) will be placed in brackets
0200    * after the diagnostic text. This option corresponds to the clang flag
0201    * \c -fdiagnostics-show-option.
0202    */
0203   CXDiagnostic_DisplayOption = 0x08,
0204
0205   /**
0206    * Display the category number associated with this diagnostic, if any.
0207    *
0208    * The category number is displayed within brackets after the diagnostic text.
0209    * This option corresponds to the clang flag
0210    * \c -fdiagnostics-show-category=id.
0211    */
0212   CXDiagnostic_DisplayCategoryId = 0x10,
0213
0214   /**
0215    * Display the category name associated with this diagnostic, if any.
0216    *
0217    * The category name is displayed within brackets after the diagnostic text.
0218    * This option corresponds to the clang flag
0219    * \c -fdiagnostics-show-category=name.
0220    */
0221   CXDiagnostic_DisplayCategoryName = 0x20
0222 };
0223
0224 /**
0225  * Format the given diagnostic in a manner that is suitable for display.
0226  *
0227  * This routine will format the given diagnostic to a string, rendering
0228  * the diagnostic according to the various options given. The
0229  * \c clang_defaultDiagnosticDisplayOptions() function returns the set of
0230  * options that most closely mimics the behavior of the clang compiler.
0231  *
0232  * \param Diagnostic The diagnostic to print.
0233  *
0234  * \param Options A set of options that control the diagnostic display,
0235  * created by combining \c CXDiagnosticDisplayOptions values.
0236  *
0237  * \returns A new string containing for formatted diagnostic.
0238  */
0239 CINDEX_LINKAGE CXString clang_formatDiagnostic(CXDiagnostic Diagnostic,
0240                                                unsigned Options);
0241
0242 /**
0243  * Retrieve the set of display options most similar to the
0244  * default behavior of the clang compiler.
0245  *
0246  * \returns A set of display options suitable for use with \c
0247  * clang_formatDiagnostic().
0248  */
0249 CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions(void);
0250
0251 /**
0252  * Determine the severity of the given diagnostic.
0253  */
0254 CINDEX_LINKAGE enum CXDiagnosticSeverity
0255     clang_getDiagnosticSeverity(CXDiagnostic);
0256
0257 /**
0258  * Retrieve the source location of the given diagnostic.
0259  *
0260  * This location is where Clang would print the caret ('^') when
0261  * displaying the diagnostic on the command line.
0262  */
0263 CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation(CXDiagnostic);
0264
0265 /**
0266  * Retrieve the text of the given diagnostic.
0267  */
0268 CINDEX_LINKAGE CXString clang_getDiagnosticSpelling(CXDiagnostic);
0269
0270 /**
0271  * Retrieve the name of the command-line option that enabled this
0272  * diagnostic.
0273  *
0274  * \param Diag The diagnostic to be queried.
0275  *
0276  * \param Disable If non-NULL, will be set to the option that disables this
0277  * diagnostic (if any).
0278  *
0279  * \returns A string that contains the command-line option used to enable this
0280  * warning, such as "-Wconversion" or "-pedantic".
0281  */
0282 CINDEX_LINKAGE CXString clang_getDiagnosticOption(CXDiagnostic Diag,
0283                                                   CXString *Disable);
0284
0285 /**
0286  * Retrieve the category number for this diagnostic.
0287  *
0288  * Diagnostics can be categorized into groups along with other, related
0289  * diagnostics (e.g., diagnostics under the same warning flag). This routine
0290  * retrieves the category number for the given diagnostic.
0291  *
0292  * \returns The number of the category that contains this diagnostic, or zero
0293  * if this diagnostic is uncategorized.
0294  */
0295 CINDEX_LINKAGE unsigned clang_getDiagnosticCategory(CXDiagnostic);
0296
0297 /**
0298  * Retrieve the name of a particular diagnostic category.  This
0299  *  is now deprecated.  Use clang_getDiagnosticCategoryText()
0300  *  instead.
0301  *
0302  * \param Category A diagnostic category number, as returned by
0303  * \c clang_getDiagnosticCategory().
0304  *
0305  * \returns The name of the given diagnostic category.
0306  */
0307 CINDEX_DEPRECATED CINDEX_LINKAGE CXString
0308 clang_getDiagnosticCategoryName(unsigned Category);
0309
0310 /**
0311  * Retrieve the diagnostic category text for a given diagnostic.
0312  *
0313  * \returns The text of the given diagnostic category.
0314  */
0315 CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText(CXDiagnostic);
0316
0317 /**
0318  * Determine the number of source ranges associated with the given
0319  * diagnostic.
0320  */
0321 CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges(CXDiagnostic);
0322
0323 /**
0324  * Retrieve a source range associated with the diagnostic.
0325  *
0326  * A diagnostic's source ranges highlight important elements in the source
0327  * code. On the command line, Clang displays source ranges by
0328  * underlining them with '~' characters.
0329  *
0330  * \param Diagnostic the diagnostic whose range is being extracted.
0331  *
0332  * \param Range the zero-based index specifying which range to
0333  *
0334  * \returns the requested source range.
0335  */
0336 CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange(CXDiagnostic Diagnostic,
0337                                                       unsigned Range);
0338
0339 /**
0340  * Determine the number of fix-it hints associated with the
0341  * given diagnostic.
0342  */
0343 CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts(CXDiagnostic Diagnostic);
0344
0345 /**
0346  * Retrieve the replacement information for a given fix-it.
0347  *
0348  * Fix-its are described in terms of a source range whose contents
0349  * should be replaced by a string. This approach generalizes over
0350  * three kinds of operations: removal of source code (the range covers
0351  * the code to be removed and the replacement string is empty),
0352  * replacement of source code (the range covers the code to be
0353  * replaced and the replacement string provides the new code), and
0354  * insertion (both the start and end of the range point at the
0355  * insertion location, and the replacement string provides the text to
0356  * insert).
0357  *
0358  * \param Diagnostic The diagnostic whose fix-its are being queried.
0359  *
0360  * \param FixIt The zero-based index of the fix-it.
0361  *
0362  * \param ReplacementRange The source range whose contents will be
0363  * replaced with the returned replacement string. Note that source
0364  * ranges are half-open ranges [a, b), so the source code should be
0365  * replaced from a and up to (but not including) b.
0366  *
0367  * \returns A string containing text that should be replace the source
0368  * code indicated by the \c ReplacementRange.
0369  */
0370 CINDEX_LINKAGE CXString clang_getDiagnosticFixIt(
0371     CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange);
0372
0373 /**
0374  * @}
0375  */
0376
0377 LLVM_CLANG_C_EXTERN_C_END
0378
0379 #endif