1 //===- VerifyDiagnosticConsumer.h - Verifying Diagnostic Client -*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_CLANG_FRONTEND_VERIFYDIAGNOSTICSCLIENT_H
11 #define LLVM_CLANG_FRONTEND_VERIFYDIAGNOSTICSCLIENT_H
13 #include "clang/Basic/Diagnostic.h"
14 #include "clang/Lex/Preprocessor.h"
15 #include "llvm/ADT/DenseMap.h"
16 #include "llvm/ADT/PointerIntPair.h"
17 #include "llvm/ADT/STLExtras.h"
23 class DiagnosticsEngine;
24 class TextDiagnosticBuffer;
27 /// VerifyDiagnosticConsumer - Create a diagnostic client which will use
28 /// markers in the input source to check that all the emitted diagnostics match
31 /// USING THE DIAGNOSTIC CHECKER:
33 /// Indicating that a line expects an error or a warning is simple. Put a
34 /// comment on the line that has the diagnostic, use:
37 /// expected-{error,warning,remark,note}
40 /// to tag if it's an expected error, remark or warning, and place the expected
41 /// text between {{ and }} markers. The full text doesn't have to be included,
42 /// only enough to ensure that the correct diagnostic was emitted.
44 /// Here's an example:
47 /// int A = B; // expected-error {{use of undeclared identifier 'B'}}
50 /// You can place as many diagnostics on one line as you wish. To make the code
51 /// more readable, you can use slash-newline to separate out the diagnostics.
53 /// Alternatively, it is possible to specify the line on which the diagnostic
54 /// should appear by appending "@<line>" to "expected-<type>", for example:
57 /// #warning some text
58 /// // expected-warning@10 {{some text}}
61 /// The line number may be absolute (as above), or relative to the current
62 /// line by prefixing the number with either '+' or '-'.
64 /// If the diagnostic is generated in a separate file, for example in a shared
65 /// header file, it may be beneficial to be able to declare the file in which
66 /// the diagnostic will appear, rather than placing the expected-* directive in
67 /// the actual file itself. This can be done using the following syntax:
70 /// // expected-error@path/include.h:15 {{error message}}
73 /// The path can be absolute or relative and the same search paths will be used
74 /// as for #include directives. The line number in an external file may be
75 /// substituted with '*' meaning that any line number will match (useful where
76 /// the included file is, for example, a system header where the actual line
77 /// number may change and is not critical).
79 /// The simple syntax above allows each specification to match exactly one
80 /// error. You can use the extended syntax to customize this. The extended
81 /// syntax is "expected-<type> <n> {{diag text}}", where \<type> is one of
82 /// "error", "warning" or "note", and \<n> is a positive integer. This allows
83 /// the diagnostic to appear as many times as specified. Example:
86 /// void f(); // expected-note 2 {{previous declaration is here}}
89 /// Where the diagnostic is expected to occur a minimum number of times, this
90 /// can be specified by appending a '+' to the number. Example:
93 /// void f(); // expected-note 0+ {{previous declaration is here}}
94 /// void g(); // expected-note 1+ {{previous declaration is here}}
97 /// In the first example, the diagnostic becomes optional, i.e. it will be
98 /// swallowed if it occurs, but will not generate an error if it does not
99 /// occur. In the second example, the diagnostic must occur at least once.
100 /// As a short-hand, "one or more" can be specified simply by '+'. Example:
103 /// void g(); // expected-note + {{previous declaration is here}}
106 /// A range can also be specified by "<n>-<m>". Example:
109 /// void f(); // expected-note 0-1 {{previous declaration is here}}
112 /// In this example, the diagnostic may appear only once, if at all.
114 /// Regex matching mode may be selected by appending '-re' to type and
115 /// including regexes wrapped in double curly braces in the directive, such as:
118 /// expected-error-re {{format specifies type 'wchar_t **' (aka '{{.+}}')}}
121 /// Examples matching error: "variable has incomplete type 'struct s'"
124 /// // expected-error {{variable has incomplete type 'struct s'}}
125 /// // expected-error {{variable has incomplete type}}
127 /// // expected-error-re {{variable has type 'struct {{.}}'}}
128 /// // expected-error-re {{variable has type 'struct {{.*}}'}}
129 /// // expected-error-re {{variable has type 'struct {{(.*)}}'}}
130 /// // expected-error-re {{variable has type 'struct{{[[:space:]](.*)}}'}}
133 /// VerifyDiagnosticConsumer expects at least one expected-* directive to
134 /// be found inside the source code. If no diagnostics are expected the
135 /// following directive can be used to indicate this:
138 /// // expected-no-diagnostics
141 class VerifyDiagnosticConsumer: public DiagnosticConsumer,
142 public CommentHandler {
144 /// Directive - Abstract class representing a parsed verify directive.
148 static Directive *create(bool RegexKind, SourceLocation DirectiveLoc,
149 SourceLocation DiagnosticLoc, bool MatchAnyLine,
150 StringRef Text, unsigned Min, unsigned Max);
152 /// Constant representing n or more matches.
153 static const unsigned MaxCount = UINT_MAX;
155 SourceLocation DirectiveLoc;
156 SourceLocation DiagnosticLoc;
157 const std::string Text;
161 virtual ~Directive() { }
163 // Returns true if directive text is valid.
164 // Otherwise returns false and populates E.
165 virtual bool isValid(std::string &Error) = 0;
167 // Returns true on match.
168 virtual bool match(StringRef S) = 0;
171 Directive(SourceLocation DirectiveLoc, SourceLocation DiagnosticLoc,
172 bool MatchAnyLine, StringRef Text, unsigned Min, unsigned Max)
173 : DirectiveLoc(DirectiveLoc), DiagnosticLoc(DiagnosticLoc),
174 Text(Text), Min(Min), Max(Max), MatchAnyLine(MatchAnyLine) {
175 assert(!DirectiveLoc.isInvalid() && "DirectiveLoc is invalid!");
176 assert(!DiagnosticLoc.isInvalid() && "DiagnosticLoc is invalid!");
180 Directive(const Directive &) LLVM_DELETED_FUNCTION;
181 void operator=(const Directive &) LLVM_DELETED_FUNCTION;
184 typedef std::vector<Directive*> DirectiveList;
186 /// ExpectedData - owns directive objects and deletes on destructor.
188 struct ExpectedData {
189 DirectiveList Errors;
190 DirectiveList Warnings;
191 DirectiveList Remarks;
195 llvm::DeleteContainerPointers(Errors);
196 llvm::DeleteContainerPointers(Warnings);
197 llvm::DeleteContainerPointers(Remarks);
198 llvm::DeleteContainerPointers(Notes);
201 ~ExpectedData() { Reset(); }
204 enum DirectiveStatus {
206 HasNoDirectivesReported,
207 HasExpectedNoDiagnostics,
208 HasOtherExpectedDirectives
212 DiagnosticsEngine &Diags;
213 DiagnosticConsumer *PrimaryClient;
214 bool OwnsPrimaryClient;
215 std::unique_ptr<TextDiagnosticBuffer> Buffer;
216 const Preprocessor *CurrentPreprocessor;
217 const LangOptions *LangOpts;
218 SourceManager *SrcManager;
219 unsigned ActiveSourceFiles;
220 DirectiveStatus Status;
223 void CheckDiagnostics();
224 void setSourceManager(SourceManager &SM) {
225 assert((!SrcManager || SrcManager == &SM) && "SourceManager changed!");
229 // These facilities are used for validation in debug builds.
230 class UnparsedFileStatus {
231 llvm::PointerIntPair<const FileEntry *, 1, bool> Data;
233 UnparsedFileStatus(const FileEntry *File, bool FoundDirectives)
234 : Data(File, FoundDirectives) {}
235 const FileEntry *getFile() const { return Data.getPointer(); }
236 bool foundDirectives() const { return Data.getInt(); }
238 typedef llvm::DenseMap<FileID, const FileEntry *> ParsedFilesMap;
239 typedef llvm::DenseMap<FileID, UnparsedFileStatus> UnparsedFilesMap;
240 ParsedFilesMap ParsedFiles;
241 UnparsedFilesMap UnparsedFiles;
244 /// Create a new verifying diagnostic client, which will issue errors to
245 /// the currently-attached diagnostic client when a diagnostic does not match
246 /// what is expected (as indicated in the source file).
247 VerifyDiagnosticConsumer(DiagnosticsEngine &Diags);
248 ~VerifyDiagnosticConsumer();
250 void BeginSourceFile(const LangOptions &LangOpts,
251 const Preprocessor *PP) override;
253 void EndSourceFile() override;
256 /// File has been processed via HandleComment.
259 /// File has diagnostics and may have directives.
262 /// File has diagnostics but guaranteed no directives.
263 IsUnparsedNoDirectives
266 /// \brief Update lists of parsed and unparsed files.
267 void UpdateParsedFileStatus(SourceManager &SM, FileID FID, ParsedStatus PS);
269 bool HandleComment(Preprocessor &PP, SourceRange Comment) override;
271 void HandleDiagnostic(DiagnosticsEngine::Level DiagLevel,
272 const Diagnostic &Info) override;
275 } // end namspace clang