1 //===--- Diagnostic.h - C Language Family Diagnostic Handling ---*- C++ -*-===//
11 /// \brief Defines the Diagnostic-related interfaces.
43 /// \brief Annotates a diagnostic with some code that should be
50 /// suppressing the diagnostic output can still result in successful
140   /// \brief The level of the diagnostic, after it has been through mapping.
197   /// Mapping info is packed into four bits per diagnostic.  The low three
203   /// A new DiagState is created and kept around when diagnostic pragmas modify
204   /// the state so that we know what is the diagnostic state at any given
227   /// \brief Represents a point in source where the diagnostic state was
230   /// 'Loc' can be null if the point represents the diagnostic state
250   /// diagnostic state due to diagnostic pragmas.
257   /// \brief Keeps the DiagState that was active during each diagnostic 'push'
277   /// \brief Finds the DiagStatePoint that contains the diagnostic state of
299   /// \brief The level of the last diagnostic emitted.
302   /// diagnostic that they follow.
308   /// \brief A function pointer that converts an opaque diagnostic
311   /// This takes the modifiers and argument that was present in the diagnostic.
314   /// diagnostic.  Implementations of this function can use this information to
328   /// \brief ID of the "delayed" diagnostic, which is a (typically
329   /// fatal) diagnostic that had to be delayed because it was found
330   /// while emitting another diagnostic.
333   /// \brief First string argument for the delayed diagnostic.
336   /// \brief Second string argument for the delayed diagnostic.
358   /// \brief Retrieve the diagnostic options.
363   /// \brief Get the current set of diagnostic mappings.
375   /// \brief Return the current diagnostic client along with ownership of that
402   /// \brief Set the diagnostic client associated with this diagnostic object.
404   /// \param ShouldOwnClient true if the diagnostic object should take
415   /// notes to emit along with a given diagnostic.
421   /// notes to emit along with a given diagnostic.
427   /// notes to emit along with a given diagnostic.
433   /// notes to emit along with a given diagnostic.
501   /// \brief Pretend that the last diagnostic issued was ignored, so any
511   /// \brief Determine whether the previous diagnostic was ignored. This can
513   /// diagnostic will be suppressed.
539   /// \param Loc The source location that this change of diagnostic state should
543   /// \brief Change an entire diagnostic group (e.g. "unknown-pragmas") to
552   /// \param Loc The source location that this change of diagnostic state should
558   /// \brief Set the warning-as-error flag for the given diagnostic group.
560   /// This function always only operates on the current diagnostic state.
565   /// \brief Set the error-as-fatal flag for the given diagnostic group.
567   /// This function always only operates on the current diagnostic state.
600   /// \brief Return an ID for a diagnostic with the specified format string and
603   /// If this is the first request for this diagnostic, it is registered and
606   /// \param FormatString A fixed diagnostic format string that will be hashed
614   /// \brief Converts a diagnostic argument (as an intptr_t) into the string
630   /// \brief Note that the prior diagnostic was emitted by some other
631   /// \c DiagnosticsEngine, and we may be attaching a note to that diagnostic.
636   /// \brief Reset the state of the diagnostic object to its initial 
644   /// \brief Determine whether the diagnostic is known to be ignored.
647   /// known for certain that the diagnostic has been suppressed at the
651   /// diagnostic state. Can be null in order to query the latest state.
658   /// object, classify the specified diagnostic ID into a Level, consumable by
666   /// diagnostic state. Can be null in order to query the latest state.
677   /// \param Loc Represents the source location associated with the diagnostic,
684   /// \brief Determine whethere there is already a diagnostic in flight.
687   /// \brief Set the "delayed" diagnostic that will be emitted once
688   /// the current diagnostic completes.
690   ///  If a diagnostic is already in-flight but the front end must
692   ///  state), this routine sets a "delayed" diagnostic that will be
693   ///  emitted after the current diagnostic completes. This should
695   ///  times. If emitting a delayed diagnostic causes a second delayed
696   ///  diagnostic to be introduced, that second delayed diagnostic
699   /// \param DiagID The ID of the diagnostic being delayed.
702   /// diagnostic. A copy of this string will be stored in the
706   /// diagnostic. A copy of this string will be stored in the
711   /// \brief Clear out the current diagnostic.
714   /// \brief Return the value associated with this diagnostic flag.
718   /// \brief Report the delayed diagnostic.
724   // diagnostic "in flight" at a time, but this seems to be a reasonable
726   // diagnostic is in flight at a time.
729   friend class Diagnostic;  variable
733   /// \brief The location of the current diagnostic that is in flight.
736   /// \brief The ID of the current diagnostic that is in flight.
738   /// This is set to ~0U when there is no diagnostic in flight.
745     /// diagnostic with more than that almost certainly has to be simplified
761   /// diagnostic.
773   /// \brief The list of ranges added to this diagnostic.
785     // If this is a pragma mapping, then set the diagnostic mapping flags so  in makeUserMapping()
795   /// \brief Used to report a diagnostic that is finally fully formed.
797   /// \returns true if the diagnostic was emitted, false if it was suppressed.
802   /// @name Diagnostic Emission
811   /// \brief Emit the current diagnostic and clear the diagnostic state.
813   /// \param Force Emit the diagnostic regardless of suppression settings.
865 /// the currently "in flight" diagnostic.  When the temporary for the builder
866 /// is destroyed, the diagnostic is issued.
877   /// \brief Status variable indicating if this diagnostic is still active.
884   /// \brief Flag indicating that this diagnostic is being emitted via a
907   /// \brief Clear out the current diagnostic.
914   /// \brief Determine whether this diagnostic is still active.
917   /// \brief Force the diagnostic builder to emit the diagnostic now.
922   /// \returns true if a diagnostic was emitted, false if the
923   /// diagnostic was suppressed.
925     // If this diagnostic is inactive, then its soul was stolen by the copy ctor  in Emit()
933     // Process the diagnostic.  in Emit()
936     // This diagnostic is dead.  in Emit()
943   /// Copy constructor.  When copied, this "takes" the diagnostic info from the
953   /// \brief Retrieve an empty diagnostic builder.
958   /// \brief Emits the diagnostic.
963   /// \brief Forces the diagnostic to be emitted.
979     assert(isActive() && "Clients must not add to cleared diagnostic!");  in AddString()
981            "Too many arguments to diagnostic!");  in AddString()
987     assert(isActive() && "Clients must not add to cleared diagnostic!");  in AddTaggedVal()
989            "Too many arguments to diagnostic!");  in AddTaggedVal()
995     assert(isActive() && "Clients must not add to cleared diagnostic!");  in AddSourceRange()
1000     assert(isActive() && "Clients must not add to cleared diagnostic!");  in AddFixItHint()
1013 /// \brief Register a value for the flag in the current diagnostic. This
1015 /// useful in cases where the diagnostic flag accepts values (e.g.,
1071 // Adds a DeclContext to the diagnostic. The enable_if template magic is here
1138 // Diagnostic
1143 /// currently in-flight diagnostic.
1144 class Diagnostic {
1148   explicit Diagnostic(const DiagnosticsEngine *DO) : DiagObj(DO) {}  in Diagnostic()  function
1149   Diagnostic(const DiagnosticsEngine *DO, StringRef storedDiagMessage)  in Diagnostic()  function
1219   /// \brief Return the number of source ranges associated with this diagnostic.
1226     assert(Idx < getNumRanges() && "Invalid diagnostic range index!");  in getRange()
1230   /// \brief Return an array reference for this diagnostic's ranges.
1248   /// \brief Format this diagnostic into a string, substituting the
1255   /// arguments stored in this diagnostic.
1261  * \brief Represents a diagnostic in a form that can be retained until its 
1274   StoredDiagnostic(DiagnosticsEngine::Level Level, const Diagnostic &Info);
1282   /// \brief Evaluates true when this object stores a diagnostic.
1328   /// \brief Callback to inform the diagnostic client that processing
1342   /// \brief Callback to inform the diagnostic client that processing
1345   /// The diagnostic client should assume that any objects made available via
1349   /// \brief Callback to inform the diagnostic client that processing of all
1360   /// \brief Handle this diagnostic, reporting it to the user or
1366                                 const Diagnostic &Info);
1369 /// \brief A diagnostic client that ignores all diagnostics.
1373                         const Diagnostic &Info) override {  in HandleDiagnostic()
1378 /// \brief Diagnostic consumer that forwards diagnostics along to an
1379 /// existing, already-initialized diagnostic consumer.
1390                         const Diagnostic &Info) override;
1408 /// Special character that the diagnostic printer will use to toggle the bold
1413 /// ProcessWarningOptions - Initialize the diagnostic client and process the