slang::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:

Public static functions

template<typename ForType>
static void setDefaultFormatter(std::shared_ptr<DiagArgFormatter> formatter)
static auto reportAll(const SourceManager& sourceManager, span<const Diagnostic> diags) -> std::string

Constructors, destructors, conversion operators

DiagnosticEngine(const SourceManager& sourceManager) explicit

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)
auto getSourceManager() const -> const SourceManager&
Gets the source manager associated with the engine.
auto getNumErrors() const -> int
auto getNumWarnings() const -> int
void clearCounts()
void setErrorLimit(int limit)
void setIgnoreAllWarnings(bool set)
void setIgnoreAllNotes(bool set)
void setWarningsAsErrors(bool set)
void setErrorsAsFatal(bool set)
void setFatalsAsErrors(bool set)
void setSeverity(DiagCode code, DiagnosticSeverity severity)
void setSeverity(const DiagGroup& group, DiagnosticSeverity severity)
Sets the severity for all of diagnostics in the given group.
auto getSeverity(DiagCode code, SourceLocation location) const -> DiagnosticSeverity
void setMessage(DiagCode code, const std::string& message)
auto getMessage(DiagCode code) const -> string_view
Gets the message currently mapped for the given diagnostic.
auto getOptionName(DiagCode code) const -> string_view
auto findFromOptionName(string_view optionName) const -> DiagCode
auto findDiagGroup(string_view name) const -> const DiagGroup*
Finds the diagnostic group with the given name, if it exists. Otherwise returns nullptr.
auto hasCustomSeverity(DiagCode code) const -> bool
void clearMappings()
void clearMappings(DiagnosticSeverity severity)
template<typename ForType>
void setFormatter(std::shared_ptr<DiagArgFormatter> formatter)
auto formatMessage(const Diagnostic& diag) const -> std::string
auto setWarningOptions(span<const std::string> options) -> Diagnostics
auto setMappingsFromPragmas() -> Diagnostics
void mapSourceRanges(SourceLocation loc, span<const SourceRange> ranges, SmallVector<SourceRange>& mapped, bool mapOriginalLocations = true) const

Function documentation

template<typename ForType>
static void slang::DiagnosticEngine::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.

static std::string slang::DiagnosticEngine::reportAll(const SourceManager& sourceManager, span<const Diagnostic> diags)

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.

slang::DiagnosticEngine::DiagnosticEngine(const SourceManager& sourceManager) explicit

Constructs a new diagnostic engine, using the specified source manager for reporting source-based information from diagnostics.

void slang::DiagnosticEngine::issue(const Diagnostic& diagnostic)

Issues a diagnostic to all registered clients. The issued diagnostic can be filtered or remapped based on current settings.

int slang::DiagnosticEngine::getNumErrors() const

Gets the number of errors and fatal errors issued so far (including all diagnostics that were remapped to be considered errors).

int slang::DiagnosticEngine::getNumWarnings() const

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 slang::DiagnosticEngine::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 slang::DiagnosticEngine::setErrorLimit(int limit)

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::DiagnosticEngine::setIgnoreAllWarnings(bool set)

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::DiagnosticEngine::setIgnoreAllNotes(bool set)

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::DiagnosticEngine::setWarningsAsErrors(bool set)

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::DiagnosticEngine::setErrorsAsFatal(bool set)

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::DiagnosticEngine::setFatalsAsErrors(bool set)

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::DiagnosticEngine::setSeverity(DiagCode code, DiagnosticSeverity severity)

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.

DiagnosticSeverity slang::DiagnosticEngine::getSeverity(DiagCode code, SourceLocation location) const

Gets the severity currently mapped for the given diagnostic, at the given location in the source code.

void slang::DiagnosticEngine::setMessage(DiagCode code, const std::string& message)

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.

string_view slang::DiagnosticEngine::getOptionName(DiagCode code) const

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.

DiagCode slang::DiagnosticEngine::findFromOptionName(string_view optionName) const

Finds a diagnostic given an option name. If no matching diagnostic is found, returns an empty diagnostic code.

bool slang::DiagnosticEngine::hasCustomSeverity(DiagCode code) const

Returns true if the given diagnostic has a custom severity mapping specified by a previous call to setSeverity(). Otherwise returns false.

void slang::DiagnosticEngine::clearMappings()

Clears out all custom mappings for diagnostics, reverting built-ins back to their defaults and removing all user-specified diagnostics.

void slang::DiagnosticEngine::clearMappings(DiagnosticSeverity severity)

Clears out all custom mappings for diagnostics that are set to the specific severity type.

template<typename ForType>
void slang::DiagnosticEngine::setFormatter(std::shared_ptr<DiagArgFormatter> formatter)

Sets a custom formatter function for the given type. This is used to provide formatting for diagnostic arguments of a custom type.

std::string slang::DiagnosticEngine::formatMessage(const Diagnostic& diag) const

Formats the given diagnostic using its arguments and the currently mapped message for its diagnostic code.

Diagnostics slang::DiagnosticEngine::setWarningOptions(span<const std::string> options)

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::DiagnosticEngine::setMappingsFromPragmas()

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.

void slang::DiagnosticEngine::mapSourceRanges(SourceLocation loc, span<const SourceRange> ranges, SmallVector<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. 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.