DiagnosticEngine class
The DiagnosticEngine is the central point for controlling how diagnostics are categorized and issued to clients.
The clients in this context are in charge of actually reporting diagnostics to the user in whatever format they prefer.
The workflow here is:
- Create a DiagnosticEngine and configure it how you desire
- Register one or more DiagnosticClient derived classes with addClient()
- Issue diagnostics by calling issue()
Public static functions
-
template<typename ForType>static void setDefaultFormatter(std::
shared_ptr<DiagArgFormatter> formatter) - Sets a custom formatter for the given type that should apply by default to all new DiagnosticEngine instances that get created.
-
template<typename TFunc>static void setDefaultSymbolPathCB(TFunc&& func)
- Sets the default callback to use for getting a symbol path for a given symbol, which will be used if a specific callback is not set on a DiagnosticEngine instance.
-
static auto reportAll(const SourceManager& sourceManager,
std::
span<const Diagnostic> diags) -> std:: string - A helper method used as a shortcut to turn all of the specified diagnostics into a human-friendly string.
Constructors, destructors, conversion operators
- DiagnosticEngine(const SourceManager& sourceManager) explicit
- Constructs a new diagnostic engine, using the specified source manager for reporting source-based information from diagnostics.
Public functions
-
void addClient(const std::
shared_ptr<DiagnosticClient>& client) - Adds a client which will receive all future diagnostics that are issued.
- void clearClients()
- Clears all previously registered clients from the engine.
- void issue(const Diagnostic& diagnostic)
- Issues a diagnostic to all registered clients.
- auto getSourceManager() const -> const SourceManager&
- Gets the source manager associated with the engine.
- auto getNumErrors() const -> int
- Gets the number of errors and fatal errors issued so far (including all diagnostics that were remapped to be considered errors).
- auto getNumWarnings() const -> int
- Gets the number of warnings issued so far (including all diagnostics that were remapped to be considered warnings but not including diagnostics that were remapped to be ignored).
- void clearCounts()
- Clears the number of errors and warnings issued, and in addition clears out the state of which include files for which we've already reported include stacks.
- void setErrorLimit(int limit)
- Sets the limit on the number of errors that will be issued (including fatal errors).
- void setIgnoreAllWarnings(bool set)
- Sets whether all warnings should be ignored.
- void setIgnoreAllNotes(bool set)
- Sets whether all notes should be ignored.
- void setWarningsAsErrors(bool set)
- Sets whether all warnings should be treated as errors.
- void setErrorsAsFatal(bool set)
- Sets whether all errors should be treated as fatal errors.
- void setFatalsAsErrors(bool set)
- Sets whether all fatal errors should be treated as normal errors.
- void setSeverity(DiagCode code, DiagnosticSeverity severity)
- Sets the severity for the given diagnostic.
- auto getSeverity(DiagCode code, SourceLocation location) const -> DiagnosticSeverity
- Gets the severity currently mapped for the given diagnostic, at the given location in the source code.
-
void setMessage(DiagCode code,
const std::
string& message) - Sets the message to use for the given diagnostic.
-
auto getMessage(DiagCode code) const -> std::
string_view - Gets the message currently mapped for the given diagnostic.
-
auto getOptionName(DiagCode code) const -> std::
string_view - Gets the option string that can be used to refer to a particular diagnostic.
-
auto findFromOptionName(std::
string_view optionName) const -> std:: span<const DiagCode> - Finds a diagnostic given an option name.
-
auto findDiagGroup(std::
string_view name) const -> const DiagGroup* - Finds the diagnostic group with the given name, if it exists. Otherwise returns nullptr.
- void clearMappings()
- Clears out all custom mappings for diagnostics, reverting built-ins back to their defaults and removing all user-specified diagnostics.
- void clearMappings(DiagnosticSeverity severity)
- Clears out all custom mappings for diagnostics that are set to the specific severity type.
-
auto addIgnorePaths(std::
string_view pattern) -> std:: error_code - Adds paths for which all warnings will be supressed.
-
auto addIgnoreMacroPaths(std::
string_view pattern) -> std:: error_code - Adds paths for which all warnings will be supressed, when looking at the original location for macro expansions (i.e.
-
template<typename ForType>void setFormatter(std::
shared_ptr<DiagArgFormatter> formatter) - Sets a custom formatter function for the given type.
-
template<typename TFunc>void setSymbolPathCB(TFunc&& func)
- Sets a callback that will be used to get a symbol path for a given symbol.
- auto getSymbolPathCB() const -> const SymbolPathCB&
- Gets the callback to use for getting a symbol path for a given symbol.
-
auto formatMessage(const Diagnostic& diag) const -> std::
string - Formats the given diagnostic using its arguments and the currently mapped message for its diagnostic code.
-
auto setWarningOptions(std::
span<const std:: string> options) -> Diagnostics - Sets diagnostic options from the given option strings, typically from a list of -W arguments passed to a command line invocation.
- auto setMappingsFromPragmas(BufferID buffer) -> Diagnostics
- Sets diagnostic options from the `pragma diagnostic entries in all of the various / source files tracked by the engine's source manager.
-
void mapSourceRanges(SourceLocation loc,
std::
span<const SourceRange> ranges, SmallVectorBase<SourceRange>& mapped, bool mapOriginalLocations = true) const - A helper function that takes a set of source ranges and translates them to be relevant to the given context location.
Function documentation
static std::
A helper method used as a shortcut to turn all of the specified diagnostics into a human-friendly string.
This is mostly intended to be used for things like tests.
void slang::
Issues a diagnostic to all registered clients.
The issued diagnostic can be filtered or remapped based on current settings.
void slang::
Sets the limit on the number of errors that will be issued (including fatal errors).
Once the limit is reached, the engine will filter all further errors. If the limit is set to zero (the default) the limit is infinite.
void slang::
Sets whether all warnings should be ignored.
Note that this does not apply to diagnostics that have an overridden severity specified via setSeverity().
void slang::
Sets whether all notes should be ignored.
Note that this does not apply to diagnostics that have an overridden severity specified via setSeverity().
void slang::
Sets whether all warnings should be treated as errors.
Note that this does not apply to diagnostics that have an overridden severity specified via setSeverity().
void slang::
Sets whether all errors should be treated as fatal errors.
Note that this does not apply to diagnostics that have an overridden severity specified via setSeverity(). Also note that if both this and setFatalsAsErrors is set, this one takes precedence.
void slang::
Sets whether all fatal errors should be treated as normal errors.
Note that this does not apply to diagnostics that have an overridden severity specified via setSeverity(). Also note that if both this and setErrorsAsFatal is set, the other one takes precedence.
void slang::
Sets the severity for the given diagnostic.
If this is a built-in diagnostic this will essentially override its default severity. Otherwise this can be used to define a new user-specified diagnostic.
void slang::
Sets the message to use for the given diagnostic.
If this is a built-in diagnostic this will essentially override its default message. Otherwise this can be used to define a new user-specified diagnostic.
std::
Gets the option string that can be used to refer to a particular diagnostic.
If the diagnostic has no option string provided, this returns an empty string.
std::
Finds a diagnostic given an option name.
If no matching diagnostic is found, returns an empty diagnostic code.
std::
Adds paths for which all warnings will be supressed.
This applies to all natural warnings, regardless of whether they've been upgraded to an error.
std::
Adds paths for which all warnings will be supressed, when looking at the original location for macro expansions (i.e.
where the macro was originally defined). This applies to all natural warnings, regardless of whether they've been upgraded to an error.
template<typename ForType>
void slang::
Sets a custom formatter function for the given type.
This is used to provide formatting for diagnostic arguments of a custom type.
Diagnostics slang::
Sets diagnostic options from the given option strings, typically from a list of -W arguments passed to a command line invocation.
Any errors encountered while parsing the options are returned via the diagnostics set.
Diagnostics slang::
Sets diagnostic options from the `pragma diagnostic entries in all of the various / source files tracked by the engine's source manager.
Any errors encountered / while applying options are returned via the diagnostics set. Diagnostics setMappingsFromPragmas();
/ Sets diagnostic options from the `pragma diagnostic entries in the given source file tracked by the engine's source manager. Any errors encountered while applying options are returned via the diagnostics set.
void slang::
A helper function that takes a set of source ranges and translates them to be relevant to the given context location.
For normal file ranges this doesn't do anything, but ranges within macro expansions get adjusted to their original expansion location in the same buffer as the context location.
If mapOriginalLocations is set to true, the returned source ranges will be specified in their original textual locations. Otherwise they will remain as macro locations.