clang 10.0.0git

Classes | Public Types | Public Member Functions | List of all members
clang::VerifyDiagnosticConsumer Class Reference

VerifyDiagnosticConsumer - Create a diagnostic client which will use markers in the input source to check that all the emitted diagnostics match those expected. More...

`#include "clang/Frontend/VerifyDiagnosticConsumer.h"`

Inheritance diagram for clang::VerifyDiagnosticConsumer:
[legend]
Collaboration diagram for clang::VerifyDiagnosticConsumer:
[legend]

## Classes
class | Directive
| Directive - Abstract class representing a parsed verify directive. More...
struct | ExpectedData
| ExpectedData - owns directive objects and deletes on destructor. More...
class | MarkerTracker

## Public Types
enum | DirectiveStatus { HasNoDirectives, HasNoDirectivesReported, HasExpectedNoDiagnostics, HasOtherExpectedDirectives }
enum | ParsedStatus { IsParsed, IsUnparsed, IsUnparsedNoDirectives }
using | DirectiveList = std::vector< std::unique_ptr< Directive > >

## Public Member Functions
| VerifyDiagnosticConsumer (DiagnosticsEngine &Diags)
| Create a new verifying diagnostic client, which will issue errors to the currently-attached diagnostic client when a diagnostic does not match what is expected (as indicated in the source file). More...
| ~VerifyDiagnosticConsumer () override
void | BeginSourceFile (const LangOptions &LangOpts, const Preprocessor *PP) override
| Callback to inform the diagnostic client that processing of a source file is beginning. More...
void | EndSourceFile () override
| Callback to inform the diagnostic client that processing of a source file has ended. More...
void | UpdateParsedFileStatus (SourceManager &SM, FileID FID, ParsedStatus PS)
| Update lists of parsed and unparsed files. More...
bool | HandleComment (Preprocessor &PP, SourceRange Comment) override
| HandleComment - Hook into the preprocessor and extract comments containing expected errors and warnings. More...
void | HandleDiagnostic (DiagnosticsEngine::Level DiagLevel, const Diagnostic &Info) override
| Handle this diagnostic, reporting it to the user or capturing it to a log as needed. More...
Public Member Functions inherited from clang::DiagnosticConsumer
| DiagnosticConsumer ()=default
virtual | ~DiagnosticConsumer ()
unsigned | getNumErrors () const
unsigned | getNumWarnings () const
virtual void | clear ()
virtual void | finish ()
| Callback to inform the diagnostic client that processing of all source files has ended. More...
virtual bool | IncludeInDiagnosticCounts () const
| Indicates whether the diagnostics handled by this DiagnosticConsumer should be included in the number of diagnostics reported by DiagnosticsEngine. More...
Public Member Functions inherited from clang::CommentHandler
virtual | ~CommentHandler ()

## Additional Inherited Members
Protected Attributes inherited from clang::DiagnosticConsumer
unsigned | NumWarnings = 0
| Number of warnings reported. More...
unsigned | NumErrors = 0
| Number of errors reported. More...

## Detailed Description

VerifyDiagnosticConsumer - Create a diagnostic client which will use markers in the input source to check that all the emitted diagnostics match those expected.

INVOKING THE DIAGNOSTIC CHECKER:

VerifyDiagnosticConsumer is typically invoked via the "-verify" option to "clang -cc1". "-verify" is equivalent to "-verify=expected", so all diagnostics are typically specified with the prefix "expected". For example:

int A = B; // expected-error {{use of undeclared identifier 'B'}}

Custom prefixes can be specified as a comma-separated sequence. Each prefix must start with a letter and contain only alphanumeric characters, hyphens, and underscores. For example, given just "-verify=foo,bar", the above diagnostic would be ignored, but the following diagnostics would be recognized:

int A = B; // foo-error {{use of undeclared identifier 'B'}}
int C = D; // bar-error {{use of undeclared identifier 'D'}}

Multiple occurrences accumulate prefixes. For example, "-verify -verify=foo,bar -verify=baz" is equivalent to "-verify=expected,foo,bar,baz".

SPECIFYING DIAGNOSTICS:

Indicating that a line expects an error or a warning is simple. Put a comment on the line that has the diagnostic, use:

expected-{error,warning,remark,note}

to tag if it's an expected error, remark or warning, and place the expected text between {{ and }} markers. The full text doesn't have to be included, only enough to ensure that the correct diagnostic was emitted.

Here's an example:

int A = B; // expected-error {{use of undeclared identifier 'B'}}

You can place as many diagnostics on one line as you wish. To make the code more readable, you can use slash-newline to separate out the diagnostics.

Alternatively, it is possible to specify the line on which the diagnostic should appear by appending "@<line>" to "expected-<type>", for example:

#warning some text
// expected-warning@10 {{some text}}

The line number may be absolute (as above), or relative to the current line by prefixing the number with either '+' or '-'.

If the diagnostic is generated in a separate file, for example in a shared header file, it may be beneficial to be able to declare the file in which the diagnostic will appear, rather than placing the expected-* directive in the actual file itself. This can be done using the following syntax:

// expected-error@path/include.h:15 {{error message}}

The path can be absolute or relative and the same search paths will be used as for #include directives. The line number in an external file may be substituted with '*' meaning that any line number will match (useful where the included file is, for example, a system header where the actual line number may change and is not critical).

As an alternative to specifying a fixed line number, the location of a diagnostic can instead be indicated by a marker of the form "#<marker>". Markers are specified by including them in a comment, and then referenced by appending the marker to the diagnostic with "@#<marker>":

#warning some text // #1
// expected-warning@#1 {{some text}}

The name of a marker used in a directive must be unique within the compilation.

The simple syntax above allows each specification to match exactly one error. You can use the extended syntax to customize this. The extended syntax is "expected-<type> <n> {{diag text}}", where <type> is one of "error", "warning" or "note", and <n> is a positive integer. This allows the diagnostic to appear as many times as specified. Example:

void f(); // expected-note 2 {{previous declaration is here}}

Where the diagnostic is expected to occur a minimum number of times, this can be specified by appending a '+' to the number. Example:

void f(); // expected-note 0+ {{previous declaration is here}}
void g(); // expected-note 1+ {{previous declaration is here}}

In the first example, the diagnostic becomes optional, i.e. it will be swallowed if it occurs, but will not generate an error if it does not occur. In the second example, the diagnostic must occur at least once. As a short-hand, "one or more" can be specified simply by '+'. Example:

void g(); // expected-note + {{previous declaration is here}}

A range can also be specified by "<n>-<m>". Example:

void f(); // expected-note 0-1 {{previous declaration is here}}

In this example, the diagnostic may appear only once, if at all.

Regex matching mode may be selected by appending '-re' to type and including regexes wrapped in double curly braces in the directive, such as:

expected-error-re {{format specifies type 'wchar_t **' (aka '{{.+}}')}}

Examples matching error: "variable has incomplete type 'struct s'"

// expected-error {{variable has incomplete type 'struct s'}}
// expected-error {{variable has incomplete type}}
// expected-error-re {{variable has type 'struct {{.}}'}}
// expected-error-re {{variable has type 'struct {{.*}}'}}
// expected-error-re {{variable has type 'struct {{(.*)}}'}}
// expected-error-re {{variable has type 'struct{{[[:space:]](.*)}}'}}

VerifyDiagnosticConsumer expects at least one expected-* directive to be found inside the source code. If no diagnostics are expected the following directive can be used to indicate this:

// expected-no-diagnostics

Definition at line 185 of file VerifyDiagnosticConsumer.h.

## Member Typedef Documentation

## ◆ DirectiveList

using clang::VerifyDiagnosticConsumer::DirectiveList = std::vector<std::unique_ptr<Directive> >

Definition at line 230 of file VerifyDiagnosticConsumer.h.

## Member Enumeration Documentation

## ◆ DirectiveStatus

enum clang::VerifyDiagnosticConsumer::DirectiveStatus

Enumerator
HasNoDirectives |
HasNoDirectivesReported |
HasExpectedNoDiagnostics |
HasOtherExpectedDirectives |

Definition at line 247 of file VerifyDiagnosticConsumer.h.

## ◆ ParsedStatus

enum clang::VerifyDiagnosticConsumer::ParsedStatus

Enumerator
IsParsed | File has been processed via HandleComment.
IsUnparsed | File has diagnostics and may have directives.
IsUnparsedNoDirectives | File has diagnostics but guaranteed no directives.

Definition at line 306 of file VerifyDiagnosticConsumer.h.

## Constructor & Destructor Documentation

## ◆ VerifyDiagnosticConsumer()

VerifyDiagnosticConsumer::VerifyDiagnosticConsumer | ( | DiagnosticsEngine & | Diags | ) |

Create a new verifying diagnostic client, which will issue errors to the currently-attached diagnostic client when a diagnostic does not match what is expected (as indicated in the source file).

Definition at line 643 of file VerifyDiagnosticConsumer.cpp.

## ◆ ~VerifyDiagnosticConsumer()

VerifyDiagnosticConsumer::~VerifyDiagnosticConsumer | ( |  | ) |
| override

Definition at line 652 of file VerifyDiagnosticConsumer.cpp.

References clang::DiagnosticsEngine::ownsClient().

## Member Function Documentation

## ◆ BeginSourceFile()

void VerifyDiagnosticConsumer::BeginSourceFile | ( | const LangOptions & | LangOpts,
|  | const Preprocessor * | PP
| ) |  |
| override virtual

Callback to inform the diagnostic client that processing of a source file is beginning.

Note that diagnostics may be emitted outside the processing of a source file, for example during the parsing of command line options. However, diagnostics with source range information are required to only be emitted in between BeginSourceFile() and EndSourceFile().

Parameters

  LangOpts | The language options for the source file being processed.
  PP | The preprocessor object being used for the source; this is optional, e.g., it may not be present when processing AST source files.

Reimplemented from clang::DiagnosticConsumer.

Definition at line 663 of file VerifyDiagnosticConsumer.cpp.

References clang::DiagnosticConsumer::BeginSourceFile(), and clang::Preprocessor::getSourceManager().

## ◆ EndSourceFile()

void VerifyDiagnosticConsumer::EndSourceFile | ( |  | ) |
| override virtual

Callback to inform the diagnostic client that processing of a source file has ended.

The diagnostic client should assume that any objects made available via BeginSourceFile() are inaccessible.

Reimplemented from clang::DiagnosticConsumer.

Definition at line 684 of file VerifyDiagnosticConsumer.cpp.

References clang::DiagnosticConsumer::EndSourceFile().

## ◆ HandleComment()

bool VerifyDiagnosticConsumer::HandleComment | ( | Preprocessor & | PP,
|  | SourceRange | Comment
| ) |  |
| override virtual

HandleComment - Hook into the preprocessor and extract comments containing expected errors and warnings.

Implements clang::CommentHandler.

Definition at line 746 of file VerifyDiagnosticConsumer.cpp.

References clang::C, clang::SourceRange::getBegin(), clang::SourceManager::getCharacterData(), clang::SourceRange::getEnd(), clang::Preprocessor::getSourceManager(), ParseDirective(), and SM.

## ◆ HandleDiagnostic()

void VerifyDiagnosticConsumer::HandleDiagnostic | ( | DiagnosticsEngine::Level | DiagLevel,
|  | const Diagnostic & | Info
| ) |  |
| override virtual

Handle this diagnostic, reporting it to the user or capturing it to a log as needed.

The default implementation just keeps track of the total number of warnings and errors.

Reimplemented from clang::DiagnosticConsumer.

Definition at line 704 of file VerifyDiagnosticConsumer.cpp.

References clang::HeaderSearch::findModuleForHeader(), clang::SourceManager::getExpansionLoc(), clang::SourceManager::getFileEntryForID(), clang::SourceManager::getFileID(), clang::Preprocessor::getHeaderSearchInfo(), clang::Diagnostic::getLocation(), clang::Diagnostic::getSourceManager(), clang::Diagnostic::hasSourceManager(), clang::SourceManager::isLoadedFileID(), IsUnparsed, IsUnparsedNoDirectives, clang::SourceLocation::isValid(), and UpdateParsedFileStatus().

## ◆ UpdateParsedFileStatus()

void VerifyDiagnosticConsumer::UpdateParsedFileStatus | ( | SourceManager & | SM,
|  | FileID | FID,
|  | ParsedStatus | PS
| ) |  |

Update lists of parsed and unparsed files.

Definition at line 1004 of file VerifyDiagnosticConsumer.cpp.

References CheckResults(), clang::Error, findDirectives(), clang::DiagnosticsEngine::getClient(), clang::DiagnosticsEngine::getDiagnosticOptions(), clang::SourceManager::getFileEntryForID(), clang::FileEntry::getName(), HasNoDirectives, HasNoDirectivesReported, clang::FileID::isInvalid(), IsParsed, IsUnparsedNoDirectives, clang::Note, clang::DiagnosticConsumer::NumErrors, PrintUnexpected(), clang::Remark, clang::DiagnosticsEngine::Report(), clang::VerifyDiagnosticConsumer::ExpectedData::Reset(), clang::DiagnosticsEngine::setClient(), clang::DiagnosticBuilder::setForceEmit(), clang::DiagnosticsEngine::takeClient(), and clang::Warning.

Referenced by HandleDiagnostic().

The documentation for this class was generated from the following files:

- include/clang/Frontend/VerifyDiagnosticConsumer.h
- lib/Frontend/VerifyDiagnosticConsumer.cpp