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