1 //===--- DiagnosticIDs.h - Diagnostic IDs Handling --------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 ///
9 /// \file
10 /// Defines the Diagnostic IDs-related interfaces.
11 ///
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_CLANG_BASIC_DIAGNOSTICIDS_H
15 #define LLVM_CLANG_BASIC_DIAGNOSTICIDS_H
16 
17 #include "clang/Basic/LLVM.h"
18 #include "llvm/ADT/IntrusiveRefCntPtr.h"
19 #include "llvm/ADT/StringRef.h"
20 #include <vector>
21 
22 namespace clang {
23   class DiagnosticsEngine;
24   class SourceLocation;
25 
26   // Import the diagnostic enums themselves.
27   namespace diag {
28     // Size of each of the diagnostic categories.
29     enum {
30       DIAG_SIZE_COMMON        =  300,
31       DIAG_SIZE_DRIVER        =  250,
32       DIAG_SIZE_FRONTEND      =  150,
33       DIAG_SIZE_SERIALIZATION =  120,
34       DIAG_SIZE_LEX           =  400,
35       DIAG_SIZE_PARSE         =  600,
36       DIAG_SIZE_AST           =  250,
37       DIAG_SIZE_COMMENT       =  100,
38       DIAG_SIZE_CROSSTU       =  100,
39       DIAG_SIZE_SEMA          = 4500,
40       DIAG_SIZE_ANALYSIS      =  100,
41       DIAG_SIZE_REFACTORING   = 1000,
42     };
43     // Start position for diagnostics.
44     enum {
45       DIAG_START_COMMON        =                          0,
46       DIAG_START_DRIVER        = DIAG_START_COMMON        + DIAG_SIZE_COMMON,
47       DIAG_START_FRONTEND      = DIAG_START_DRIVER        + DIAG_SIZE_DRIVER,
48       DIAG_START_SERIALIZATION = DIAG_START_FRONTEND      + DIAG_SIZE_FRONTEND,
49       DIAG_START_LEX           = DIAG_START_SERIALIZATION + DIAG_SIZE_SERIALIZATION,
50       DIAG_START_PARSE         = DIAG_START_LEX           + DIAG_SIZE_LEX,
51       DIAG_START_AST           = DIAG_START_PARSE         + DIAG_SIZE_PARSE,
52       DIAG_START_COMMENT       = DIAG_START_AST           + DIAG_SIZE_AST,
53       DIAG_START_CROSSTU       = DIAG_START_COMMENT       + DIAG_SIZE_COMMENT,
54       DIAG_START_SEMA          = DIAG_START_CROSSTU       + DIAG_SIZE_CROSSTU,
55       DIAG_START_ANALYSIS      = DIAG_START_SEMA          + DIAG_SIZE_SEMA,
56       DIAG_START_REFACTORING   = DIAG_START_ANALYSIS      + DIAG_SIZE_ANALYSIS,
57       DIAG_UPPER_LIMIT         = DIAG_START_REFACTORING   + DIAG_SIZE_REFACTORING
58     };
59 
60     class CustomDiagInfo;
61 
62     /// All of the diagnostics that can be emitted by the frontend.
63     typedef unsigned kind;
64 
65     // Get typedefs for common diagnostics.
66     enum {
67 #define DIAG(ENUM, FLAGS, DEFAULT_MAPPING, DESC, GROUP, SFINAE, CATEGORY,      \
68              NOWERROR, SHOWINSYSHEADER, DEFFERABLE)                            \
69   ENUM,
70 #define COMMONSTART
71 #include "clang/Basic/DiagnosticCommonKinds.inc"
72       NUM_BUILTIN_COMMON_DIAGNOSTICS
73 #undef DIAG
74     };
75 
76     /// Enum values that allow the client to map NOTEs, WARNINGs, and EXTENSIONs
77     /// to either Ignore (nothing), Remark (emit a remark), Warning
78     /// (emit a warning) or Error (emit as an error).  It allows clients to
79     /// map ERRORs to Error or Fatal (stop emitting diagnostics after this one).
80     enum class Severity {
81       // NOTE: 0 means "uncomputed".
82       Ignored = 1, ///< Do not present this diagnostic, ignore it.
83       Remark = 2,  ///< Present this diagnostic as a remark.
84       Warning = 3, ///< Present this diagnostic as a warning.
85       Error = 4,   ///< Present this diagnostic as an error.
86       Fatal = 5    ///< Present this diagnostic as a fatal error.
87     };
88 
89     /// Flavors of diagnostics we can emit. Used to filter for a particular
90     /// kind of diagnostic (for instance, for -W/-R flags).
91     enum class Flavor {
92       WarningOrError, ///< A diagnostic that indicates a problem or potential
93                       ///< problem. Can be made fatal by -Werror.
94       Remark          ///< A diagnostic that indicates normal progress through
95                       ///< compilation.
96     };
97   }
98 
99 class DiagnosticMapping {
100   unsigned Severity : 3;
101   unsigned IsUser : 1;
102   unsigned IsPragma : 1;
103   unsigned HasNoWarningAsError : 1;
104   unsigned HasNoErrorAsFatal : 1;
105   unsigned WasUpgradedFromWarning : 1;
106 
107 public:
108   static DiagnosticMapping Make(diag::Severity Severity, bool IsUser,
109                                 bool IsPragma) {
110     DiagnosticMapping Result;
111     Result.Severity = (unsigned)Severity;
112     Result.IsUser = IsUser;
113     Result.IsPragma = IsPragma;
114     Result.HasNoWarningAsError = 0;
115     Result.HasNoErrorAsFatal = 0;
116     Result.WasUpgradedFromWarning = 0;
117     return Result;
118   }
119 
120   diag::Severity getSeverity() const { return (diag::Severity)Severity; }
121   void setSeverity(diag::Severity Value) { Severity = (unsigned)Value; }
122 
123   bool isUser() const { return IsUser; }
124   bool isPragma() const { return IsPragma; }
125 
126   bool isErrorOrFatal() const {
127     return getSeverity() == diag::Severity::Error ||
128            getSeverity() == diag::Severity::Fatal;
129   }
130 
131   bool hasNoWarningAsError() const { return HasNoWarningAsError; }
132   void setNoWarningAsError(bool Value) { HasNoWarningAsError = Value; }
133 
134   bool hasNoErrorAsFatal() const { return HasNoErrorAsFatal; }
135   void setNoErrorAsFatal(bool Value) { HasNoErrorAsFatal = Value; }
136 
137   /// Whether this mapping attempted to map the diagnostic to a warning, but
138   /// was overruled because the diagnostic was already mapped to an error or
139   /// fatal error.
140   bool wasUpgradedFromWarning() const { return WasUpgradedFromWarning; }
141   void setUpgradedFromWarning(bool Value) { WasUpgradedFromWarning = Value; }
142 
143   /// Serialize this mapping as a raw integer.
144   unsigned serialize() const {
145     return (IsUser << 7) | (IsPragma << 6) | (HasNoWarningAsError << 5) |
146            (HasNoErrorAsFatal << 4) | (WasUpgradedFromWarning << 3) | Severity;
147   }
148   /// Deserialize a mapping.
149   static DiagnosticMapping deserialize(unsigned Bits) {
150     DiagnosticMapping Result;
151     Result.IsUser = (Bits >> 7) & 1;
152     Result.IsPragma = (Bits >> 6) & 1;
153     Result.HasNoWarningAsError = (Bits >> 5) & 1;
154     Result.HasNoErrorAsFatal = (Bits >> 4) & 1;
155     Result.WasUpgradedFromWarning = (Bits >> 3) & 1;
156     Result.Severity = Bits & 0x7;
157     return Result;
158   }
159 };
160 
161 /// Used for handling and querying diagnostic IDs.
162 ///
163 /// Can be used and shared by multiple Diagnostics for multiple translation units.
164 class DiagnosticIDs : public RefCountedBase<DiagnosticIDs> {
165 public:
166   /// The level of the diagnostic, after it has been through mapping.
167   enum Level {
168     Ignored, Note, Remark, Warning, Error, Fatal
169   };
170 
171 private:
172   /// Information for uniquing and looking up custom diags.
173   std::unique_ptr<diag::CustomDiagInfo> CustomDiagInfo;
174 
175 public:
176   DiagnosticIDs();
177   ~DiagnosticIDs();
178 
179   /// Return an ID for a diagnostic with the specified format string and
180   /// level.
181   ///
182   /// If this is the first request for this diagnostic, it is registered and
183   /// created, otherwise the existing ID is returned.
184 
185   // FIXME: Replace this function with a create-only facilty like
186   // createCustomDiagIDFromFormatString() to enforce safe usage. At the time of
187   // writing, nearly all callers of this function were invalid.
188   unsigned getCustomDiagID(Level L, StringRef FormatString);
189 
190   //===--------------------------------------------------------------------===//
191   // Diagnostic classification and reporting interfaces.
192   //
193 
194   /// Given a diagnostic ID, return a description of the issue.
195   StringRef getDescription(unsigned DiagID) const;
196 
197   /// Return true if the unmapped diagnostic levelof the specified
198   /// diagnostic ID is a Warning or Extension.
199   ///
200   /// This only works on builtin diagnostics, not custom ones, and is not
201   /// legal to call on NOTEs.
202   static bool isBuiltinWarningOrExtension(unsigned DiagID);
203 
204   /// Return true if the specified diagnostic is mapped to errors by
205   /// default.
206   static bool isDefaultMappingAsError(unsigned DiagID);
207 
208   /// Determine whether the given built-in diagnostic ID is a Note.
209   static bool isBuiltinNote(unsigned DiagID);
210 
211   /// Determine whether the given built-in diagnostic ID is for an
212   /// extension of some sort.
213   static bool isBuiltinExtensionDiag(unsigned DiagID) {
214     bool ignored;
215     return isBuiltinExtensionDiag(DiagID, ignored);
216   }
217 
218   /// Determine whether the given built-in diagnostic ID is for an
219   /// extension of some sort, and whether it is enabled by default.
220   ///
221   /// This also returns EnabledByDefault, which is set to indicate whether the
222   /// diagnostic is ignored by default (in which case -pedantic enables it) or
223   /// treated as a warning/error by default.
224   ///
225   static bool isBuiltinExtensionDiag(unsigned DiagID, bool &EnabledByDefault);
226 
227 
228   /// Return the lowest-level warning option that enables the specified
229   /// diagnostic.
230   ///
231   /// If there is no -Wfoo flag that controls the diagnostic, this returns null.
232   static StringRef getWarningOptionForDiag(unsigned DiagID);
233 
234   /// Return the category number that a specified \p DiagID belongs to,
235   /// or 0 if no category.
236   static unsigned getCategoryNumberForDiag(unsigned DiagID);
237 
238   /// Return the number of diagnostic categories.
239   static unsigned getNumberOfCategories();
240 
241   /// Given a category ID, return the name of the category.
242   static StringRef getCategoryNameFromID(unsigned CategoryID);
243 
244   /// Return true if a given diagnostic falls into an ARC diagnostic
245   /// category.
246   static bool isARCDiagnostic(unsigned DiagID);
247 
248   /// Enumeration describing how the emission of a diagnostic should
249   /// be treated when it occurs during C++ template argument deduction.
250   enum SFINAEResponse {
251     /// The diagnostic should not be reported, but it should cause
252     /// template argument deduction to fail.
253     ///
254     /// The vast majority of errors that occur during template argument
255     /// deduction fall into this category.
256     SFINAE_SubstitutionFailure,
257 
258     /// The diagnostic should be suppressed entirely.
259     ///
260     /// Warnings generally fall into this category.
261     SFINAE_Suppress,
262 
263     /// The diagnostic should be reported.
264     ///
265     /// The diagnostic should be reported. Various fatal errors (e.g.,
266     /// template instantiation depth exceeded) fall into this category.
267     SFINAE_Report,
268 
269     /// The diagnostic is an access-control diagnostic, which will be
270     /// substitution failures in some contexts and reported in others.
271     SFINAE_AccessControl
272   };
273 
274   /// Determines whether the given built-in diagnostic ID is
275   /// for an error that is suppressed if it occurs during C++ template
276   /// argument deduction.
277   ///
278   /// When an error is suppressed due to SFINAE, the template argument
279   /// deduction fails but no diagnostic is emitted. Certain classes of
280   /// errors, such as those errors that involve C++ access control,
281   /// are not SFINAE errors.
282   static SFINAEResponse getDiagnosticSFINAEResponse(unsigned DiagID);
283 
284   /// Whether the diagnostic message can be deferred.
285   ///
286   /// For single source offloading languages, a diagnostic message occurred
287   /// in a device host function may be deferred until the function is sure
288   /// to be emitted.
289   static bool isDeferrable(unsigned DiagID);
290 
291   /// Get the string of all diagnostic flags.
292   ///
293   /// \returns A list of all diagnostics flags as they would be written in a
294   /// command line invocation including their `no-` variants. For example:
295   /// `{"-Wempty-body", "-Wno-empty-body", ...}`
296   static std::vector<std::string> getDiagnosticFlags();
297 
298   /// Get the set of all diagnostic IDs in the group with the given name.
299   ///
300   /// \param[out] Diags - On return, the diagnostics in the group.
301   /// \returns \c true if the given group is unknown, \c false otherwise.
302   bool getDiagnosticsInGroup(diag::Flavor Flavor, StringRef Group,
303                              SmallVectorImpl<diag::kind> &Diags) const;
304 
305   /// Get the set of all diagnostic IDs.
306   static void getAllDiagnostics(diag::Flavor Flavor,
307                                 std::vector<diag::kind> &Diags);
308 
309   /// Get the diagnostic option with the closest edit distance to the
310   /// given group name.
311   static StringRef getNearestOption(diag::Flavor Flavor, StringRef Group);
312 
313 private:
314   /// Classify the specified diagnostic ID into a Level, consumable by
315   /// the DiagnosticClient.
316   ///
317   /// The classification is based on the way the client configured the
318   /// DiagnosticsEngine object.
319   ///
320   /// \param Loc The source location for which we are interested in finding out
321   /// the diagnostic state. Can be null in order to query the latest state.
322   DiagnosticIDs::Level
323   getDiagnosticLevel(unsigned DiagID, SourceLocation Loc,
324                      const DiagnosticsEngine &Diag) const LLVM_READONLY;
325 
326   diag::Severity
327   getDiagnosticSeverity(unsigned DiagID, SourceLocation Loc,
328                         const DiagnosticsEngine &Diag) const LLVM_READONLY;
329 
330   /// Used to report a diagnostic that is finally fully formed.
331   ///
332   /// \returns \c true if the diagnostic was emitted, \c false if it was
333   /// suppressed.
334   bool ProcessDiag(DiagnosticsEngine &Diag) const;
335 
336   /// Used to emit a diagnostic that is finally fully formed,
337   /// ignoring suppression.
338   void EmitDiag(DiagnosticsEngine &Diag, Level DiagLevel) const;
339 
340   /// Whether the diagnostic may leave the AST in a state where some
341   /// invariants can break.
342   bool isUnrecoverable(unsigned DiagID) const;
343 
344   friend class DiagnosticsEngine;
345 };
346 
347 }  // end namespace clang
348 
349 #endif
350