1 //===--- PPCallbacks.h - Callbacks for Preprocessor actions -----*- 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 //===----------------------------------------------------------------------===//
11 /// \brief Defines the PPCallbacks interface.
13 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_CLANG_LEX_PPCALLBACKS_H
16 #define LLVM_CLANG_LEX_PPCALLBACKS_H
18 #include "clang/Basic/DiagnosticIDs.h"
19 #include "clang/Basic/SourceLocation.h"
20 #include "clang/Basic/SourceManager.h"
21 #include "clang/Lex/ModuleLoader.h"
22 #include "clang/Lex/Pragma.h"
23 #include "llvm/ADT/StringRef.h"
28 class MacroDefinition;
32 /// \brief This interface provides a way to observe the actions of the
33 /// preprocessor as it does its thing.
35 /// Clients can define their hooks here to implement preprocessor level tools.
38 virtual ~PPCallbacks();
40 enum FileChangeReason {
41 EnterFile, ExitFile, SystemHeaderPragma, RenameFile
44 /// \brief Callback invoked whenever a source file is entered or exited.
46 /// \param Loc Indicates the new location.
47 /// \param PrevFID the file that was exited if \p Reason is ExitFile.
48 virtual void FileChanged(SourceLocation Loc, FileChangeReason Reason,
49 SrcMgr::CharacteristicKind FileType,
50 FileID PrevFID = FileID()) {
53 /// \brief Callback invoked whenever a source file is skipped as the result
54 /// of header guard optimization.
56 /// \param SkippedFile The file that is skipped instead of entering \#include
58 /// \param FilenameTok The file name token in \#include "FileName" directive
59 /// or macro expanded file name token from \#include MACRO(PARAMS) directive.
60 /// Note that FilenameTok contains corresponding quotes/angles symbols.
61 virtual void FileSkipped(const FileEntry &SkippedFile,
62 const Token &FilenameTok,
63 SrcMgr::CharacteristicKind FileType) {
66 /// \brief Callback invoked whenever an inclusion directive results in a
67 /// file-not-found error.
69 /// \param FileName The name of the file being included, as written in the
72 /// \param RecoveryPath If this client indicates that it can recover from
73 /// this missing file, the client should set this as an additional header
76 /// \returns true to indicate that the preprocessor should attempt to recover
77 /// by adding \p RecoveryPath as a header search path.
78 virtual bool FileNotFound(StringRef FileName,
79 SmallVectorImpl<char> &RecoveryPath) {
83 /// \brief Callback invoked whenever an inclusion directive of
84 /// any kind (\c \#include, \c \#import, etc.) has been processed, regardless
85 /// of whether the inclusion will actually result in an inclusion.
87 /// \param HashLoc The location of the '#' that starts the inclusion
90 /// \param IncludeTok The token that indicates the kind of inclusion
91 /// directive, e.g., 'include' or 'import'.
93 /// \param FileName The name of the file being included, as written in the
96 /// \param IsAngled Whether the file name was enclosed in angle brackets;
97 /// otherwise, it was enclosed in quotes.
99 /// \param FilenameRange The character range of the quotes or angle brackets
100 /// for the written file name.
102 /// \param File The actual file that may be included by this inclusion
105 /// \param SearchPath Contains the search path which was used to find the file
106 /// in the file system. If the file was found via an absolute include path,
107 /// SearchPath will be empty. For framework includes, the SearchPath and
108 /// RelativePath will be split up. For example, if an include of "Some/Some.h"
109 /// is found via the framework path
110 /// "path/to/Frameworks/Some.framework/Headers/Some.h", SearchPath will be
111 /// "path/to/Frameworks/Some.framework/Headers" and RelativePath will be
114 /// \param RelativePath The path relative to SearchPath, at which the include
115 /// file was found. This is equal to FileName except for framework includes.
117 /// \param Imported The module, whenever an inclusion directive was
118 /// automatically turned into a module import or null otherwise.
120 virtual void InclusionDirective(SourceLocation HashLoc,
121 const Token &IncludeTok,
124 CharSourceRange FilenameRange,
125 const FileEntry *File,
126 StringRef SearchPath,
127 StringRef RelativePath,
128 const Module *Imported) {
131 /// \brief Callback invoked whenever there was an explicit module-import
134 /// \param ImportLoc The location of import directive token.
136 /// \param Path The identifiers (and their locations) of the module
137 /// "path", e.g., "std.vector" would be split into "std" and "vector".
139 /// \param Imported The imported module; can be null if importing failed.
141 virtual void moduleImport(SourceLocation ImportLoc,
143 const Module *Imported) {
146 /// \brief Callback invoked when the end of the main file is reached.
148 /// No subsequent callbacks will be made.
149 virtual void EndOfMainFile() {
152 /// \brief Callback invoked when a \#ident or \#sccs directive is read.
153 /// \param Loc The location of the directive.
154 /// \param str The text of the directive.
156 virtual void Ident(SourceLocation Loc, StringRef str) {
159 /// \brief Callback invoked when start reading any pragma directive.
160 virtual void PragmaDirective(SourceLocation Loc,
161 PragmaIntroducerKind Introducer) {
164 /// \brief Callback invoked when a \#pragma comment directive is read.
165 virtual void PragmaComment(SourceLocation Loc, const IdentifierInfo *Kind,
169 /// \brief Callback invoked when a \#pragma detect_mismatch directive is
171 virtual void PragmaDetectMismatch(SourceLocation Loc, StringRef Name,
175 /// \brief Callback invoked when a \#pragma clang __debug directive is read.
176 /// \param Loc The location of the debug directive.
177 /// \param DebugType The identifier following __debug.
178 virtual void PragmaDebug(SourceLocation Loc, StringRef DebugType) {
181 /// \brief Determines the kind of \#pragma invoking a call to PragmaMessage.
182 enum PragmaMessageKind {
183 /// \brief \#pragma message has been invoked.
186 /// \brief \#pragma GCC warning has been invoked.
189 /// \brief \#pragma GCC error has been invoked.
193 /// \brief Callback invoked when a \#pragma message directive is read.
194 /// \param Loc The location of the message directive.
195 /// \param Namespace The namespace of the message directive.
196 /// \param Kind The type of the message directive.
197 /// \param Str The text of the message directive.
198 virtual void PragmaMessage(SourceLocation Loc, StringRef Namespace,
199 PragmaMessageKind Kind, StringRef Str) {
202 /// \brief Callback invoked when a \#pragma gcc diagnostic push directive
204 virtual void PragmaDiagnosticPush(SourceLocation Loc,
205 StringRef Namespace) {
208 /// \brief Callback invoked when a \#pragma gcc diagnostic pop directive
210 virtual void PragmaDiagnosticPop(SourceLocation Loc,
211 StringRef Namespace) {
214 /// \brief Callback invoked when a \#pragma gcc diagnostic directive is read.
215 virtual void PragmaDiagnostic(SourceLocation Loc, StringRef Namespace,
216 diag::Severity mapping, StringRef Str) {}
218 /// \brief Called when an OpenCL extension is either disabled or
219 /// enabled with a pragma.
220 virtual void PragmaOpenCLExtension(SourceLocation NameLoc,
221 const IdentifierInfo *Name,
222 SourceLocation StateLoc, unsigned State) {
225 /// \brief Callback invoked when a \#pragma warning directive is read.
226 virtual void PragmaWarning(SourceLocation Loc, StringRef WarningSpec,
230 /// \brief Callback invoked when a \#pragma warning(push) directive is read.
231 virtual void PragmaWarningPush(SourceLocation Loc, int Level) {
234 /// \brief Callback invoked when a \#pragma warning(pop) directive is read.
235 virtual void PragmaWarningPop(SourceLocation Loc) {
238 /// \brief Callback invoked when a \#pragma clang assume_nonnull begin directive
240 virtual void PragmaAssumeNonNullBegin(SourceLocation Loc) {}
242 /// \brief Callback invoked when a \#pragma clang assume_nonnull end directive
244 virtual void PragmaAssumeNonNullEnd(SourceLocation Loc) {}
246 /// \brief Called by Preprocessor::HandleMacroExpandedIdentifier when a
247 /// macro invocation is found.
248 virtual void MacroExpands(const Token &MacroNameTok,
249 const MacroDefinition &MD, SourceRange Range,
250 const MacroArgs *Args) {}
252 /// \brief Hook called whenever a macro definition is seen.
253 virtual void MacroDefined(const Token &MacroNameTok,
254 const MacroDirective *MD) {
257 /// \brief Hook called whenever a macro \#undef is seen.
258 /// \param MacroNameTok The active Token
259 /// \param MD A MacroDefinition for the named macro.
260 /// \param Undef New MacroDirective if the macro was defined, null otherwise.
262 /// MD is released immediately following this callback.
263 virtual void MacroUndefined(const Token &MacroNameTok,
264 const MacroDefinition &MD,
265 const MacroDirective *Undef) {
268 /// \brief Hook called whenever the 'defined' operator is seen.
269 /// \param MD The MacroDirective if the name was a macro, null otherwise.
270 virtual void Defined(const Token &MacroNameTok, const MacroDefinition &MD,
274 /// \brief Hook called when a source range is skipped.
275 /// \param Range The SourceRange that was skipped. The range begins at the
276 /// \#if/\#else directive and ends after the \#endif/\#else directive.
277 /// \param EndifLoc The end location of the 'endif' token, which may precede
278 /// the range skipped by the directive (e.g excluding comments after an
280 virtual void SourceRangeSkipped(SourceRange Range, SourceLocation EndifLoc) {
283 enum ConditionValueKind {
284 CVK_NotEvaluated, CVK_False, CVK_True
287 /// \brief Hook called whenever an \#if is seen.
288 /// \param Loc the source location of the directive.
289 /// \param ConditionRange The SourceRange of the expression being tested.
290 /// \param ConditionValue The evaluated value of the condition.
292 // FIXME: better to pass in a list (or tree!) of Tokens.
293 virtual void If(SourceLocation Loc, SourceRange ConditionRange,
294 ConditionValueKind ConditionValue) {
297 /// \brief Hook called whenever an \#elif is seen.
298 /// \param Loc the source location of the directive.
299 /// \param ConditionRange The SourceRange of the expression being tested.
300 /// \param ConditionValue The evaluated value of the condition.
301 /// \param IfLoc the source location of the \#if/\#ifdef/\#ifndef directive.
302 // FIXME: better to pass in a list (or tree!) of Tokens.
303 virtual void Elif(SourceLocation Loc, SourceRange ConditionRange,
304 ConditionValueKind ConditionValue, SourceLocation IfLoc) {
307 /// \brief Hook called whenever an \#ifdef is seen.
308 /// \param Loc the source location of the directive.
309 /// \param MacroNameTok Information on the token being tested.
310 /// \param MD The MacroDefinition if the name was a macro, null otherwise.
311 virtual void Ifdef(SourceLocation Loc, const Token &MacroNameTok,
312 const MacroDefinition &MD) {
315 /// \brief Hook called whenever an \#ifndef is seen.
316 /// \param Loc the source location of the directive.
317 /// \param MacroNameTok Information on the token being tested.
318 /// \param MD The MacroDefiniton if the name was a macro, null otherwise.
319 virtual void Ifndef(SourceLocation Loc, const Token &MacroNameTok,
320 const MacroDefinition &MD) {
323 /// \brief Hook called whenever an \#else is seen.
324 /// \param Loc the source location of the directive.
325 /// \param IfLoc the source location of the \#if/\#ifdef/\#ifndef directive.
326 virtual void Else(SourceLocation Loc, SourceLocation IfLoc) {
329 /// \brief Hook called whenever an \#endif is seen.
330 /// \param Loc the source location of the directive.
331 /// \param IfLoc the source location of the \#if/\#ifdef/\#ifndef directive.
332 virtual void Endif(SourceLocation Loc, SourceLocation IfLoc) {
336 /// \brief Simple wrapper class for chaining callbacks.
337 class PPChainedCallbacks : public PPCallbacks {
338 virtual void anchor();
339 std::unique_ptr<PPCallbacks> First, Second;
342 PPChainedCallbacks(std::unique_ptr<PPCallbacks> _First,
343 std::unique_ptr<PPCallbacks> _Second)
344 : First(std::move(_First)), Second(std::move(_Second)) {}
346 void FileChanged(SourceLocation Loc, FileChangeReason Reason,
347 SrcMgr::CharacteristicKind FileType,
348 FileID PrevFID) override {
349 First->FileChanged(Loc, Reason, FileType, PrevFID);
350 Second->FileChanged(Loc, Reason, FileType, PrevFID);
353 void FileSkipped(const FileEntry &SkippedFile,
354 const Token &FilenameTok,
355 SrcMgr::CharacteristicKind FileType) override {
356 First->FileSkipped(SkippedFile, FilenameTok, FileType);
357 Second->FileSkipped(SkippedFile, FilenameTok, FileType);
360 bool FileNotFound(StringRef FileName,
361 SmallVectorImpl<char> &RecoveryPath) override {
362 return First->FileNotFound(FileName, RecoveryPath) ||
363 Second->FileNotFound(FileName, RecoveryPath);
366 void InclusionDirective(SourceLocation HashLoc, const Token &IncludeTok,
367 StringRef FileName, bool IsAngled,
368 CharSourceRange FilenameRange, const FileEntry *File,
369 StringRef SearchPath, StringRef RelativePath,
370 const Module *Imported) override {
371 First->InclusionDirective(HashLoc, IncludeTok, FileName, IsAngled,
372 FilenameRange, File, SearchPath, RelativePath,
374 Second->InclusionDirective(HashLoc, IncludeTok, FileName, IsAngled,
375 FilenameRange, File, SearchPath, RelativePath,
379 void moduleImport(SourceLocation ImportLoc, ModuleIdPath Path,
380 const Module *Imported) override {
381 First->moduleImport(ImportLoc, Path, Imported);
382 Second->moduleImport(ImportLoc, Path, Imported);
385 void EndOfMainFile() override {
386 First->EndOfMainFile();
387 Second->EndOfMainFile();
390 void Ident(SourceLocation Loc, StringRef str) override {
391 First->Ident(Loc, str);
392 Second->Ident(Loc, str);
395 void PragmaDirective(SourceLocation Loc,
396 PragmaIntroducerKind Introducer) override {
397 First->PragmaDirective(Loc, Introducer);
398 Second->PragmaDirective(Loc, Introducer);
401 void PragmaComment(SourceLocation Loc, const IdentifierInfo *Kind,
402 StringRef Str) override {
403 First->PragmaComment(Loc, Kind, Str);
404 Second->PragmaComment(Loc, Kind, Str);
407 void PragmaDetectMismatch(SourceLocation Loc, StringRef Name,
408 StringRef Value) override {
409 First->PragmaDetectMismatch(Loc, Name, Value);
410 Second->PragmaDetectMismatch(Loc, Name, Value);
413 void PragmaDebug(SourceLocation Loc, StringRef DebugType) override {
414 First->PragmaDebug(Loc, DebugType);
415 Second->PragmaDebug(Loc, DebugType);
418 void PragmaMessage(SourceLocation Loc, StringRef Namespace,
419 PragmaMessageKind Kind, StringRef Str) override {
420 First->PragmaMessage(Loc, Namespace, Kind, Str);
421 Second->PragmaMessage(Loc, Namespace, Kind, Str);
424 void PragmaDiagnosticPush(SourceLocation Loc, StringRef Namespace) override {
425 First->PragmaDiagnosticPush(Loc, Namespace);
426 Second->PragmaDiagnosticPush(Loc, Namespace);
429 void PragmaDiagnosticPop(SourceLocation Loc, StringRef Namespace) override {
430 First->PragmaDiagnosticPop(Loc, Namespace);
431 Second->PragmaDiagnosticPop(Loc, Namespace);
434 void PragmaDiagnostic(SourceLocation Loc, StringRef Namespace,
435 diag::Severity mapping, StringRef Str) override {
436 First->PragmaDiagnostic(Loc, Namespace, mapping, Str);
437 Second->PragmaDiagnostic(Loc, Namespace, mapping, Str);
440 void PragmaOpenCLExtension(SourceLocation NameLoc, const IdentifierInfo *Name,
441 SourceLocation StateLoc, unsigned State) override {
442 First->PragmaOpenCLExtension(NameLoc, Name, StateLoc, State);
443 Second->PragmaOpenCLExtension(NameLoc, Name, StateLoc, State);
446 void PragmaWarning(SourceLocation Loc, StringRef WarningSpec,
447 ArrayRef<int> Ids) override {
448 First->PragmaWarning(Loc, WarningSpec, Ids);
449 Second->PragmaWarning(Loc, WarningSpec, Ids);
452 void PragmaWarningPush(SourceLocation Loc, int Level) override {
453 First->PragmaWarningPush(Loc, Level);
454 Second->PragmaWarningPush(Loc, Level);
457 void PragmaWarningPop(SourceLocation Loc) override {
458 First->PragmaWarningPop(Loc);
459 Second->PragmaWarningPop(Loc);
462 void PragmaAssumeNonNullBegin(SourceLocation Loc) override {
463 First->PragmaAssumeNonNullBegin(Loc);
464 Second->PragmaAssumeNonNullBegin(Loc);
467 void PragmaAssumeNonNullEnd(SourceLocation Loc) override {
468 First->PragmaAssumeNonNullEnd(Loc);
469 Second->PragmaAssumeNonNullEnd(Loc);
472 void MacroExpands(const Token &MacroNameTok, const MacroDefinition &MD,
473 SourceRange Range, const MacroArgs *Args) override {
474 First->MacroExpands(MacroNameTok, MD, Range, Args);
475 Second->MacroExpands(MacroNameTok, MD, Range, Args);
478 void MacroDefined(const Token &MacroNameTok,
479 const MacroDirective *MD) override {
480 First->MacroDefined(MacroNameTok, MD);
481 Second->MacroDefined(MacroNameTok, MD);
484 void MacroUndefined(const Token &MacroNameTok,
485 const MacroDefinition &MD,
486 const MacroDirective *Undef) override {
487 First->MacroUndefined(MacroNameTok, MD, Undef);
488 Second->MacroUndefined(MacroNameTok, MD, Undef);
491 void Defined(const Token &MacroNameTok, const MacroDefinition &MD,
492 SourceRange Range) override {
493 First->Defined(MacroNameTok, MD, Range);
494 Second->Defined(MacroNameTok, MD, Range);
497 void SourceRangeSkipped(SourceRange Range, SourceLocation EndifLoc) override {
498 First->SourceRangeSkipped(Range, EndifLoc);
499 Second->SourceRangeSkipped(Range, EndifLoc);
502 /// \brief Hook called whenever an \#if is seen.
503 void If(SourceLocation Loc, SourceRange ConditionRange,
504 ConditionValueKind ConditionValue) override {
505 First->If(Loc, ConditionRange, ConditionValue);
506 Second->If(Loc, ConditionRange, ConditionValue);
509 /// \brief Hook called whenever an \#elif is seen.
510 void Elif(SourceLocation Loc, SourceRange ConditionRange,
511 ConditionValueKind ConditionValue, SourceLocation IfLoc) override {
512 First->Elif(Loc, ConditionRange, ConditionValue, IfLoc);
513 Second->Elif(Loc, ConditionRange, ConditionValue, IfLoc);
516 /// \brief Hook called whenever an \#ifdef is seen.
517 void Ifdef(SourceLocation Loc, const Token &MacroNameTok,
518 const MacroDefinition &MD) override {
519 First->Ifdef(Loc, MacroNameTok, MD);
520 Second->Ifdef(Loc, MacroNameTok, MD);
523 /// \brief Hook called whenever an \#ifndef is seen.
524 void Ifndef(SourceLocation Loc, const Token &MacroNameTok,
525 const MacroDefinition &MD) override {
526 First->Ifndef(Loc, MacroNameTok, MD);
527 Second->Ifndef(Loc, MacroNameTok, MD);
530 /// \brief Hook called whenever an \#else is seen.
531 void Else(SourceLocation Loc, SourceLocation IfLoc) override {
532 First->Else(Loc, IfLoc);
533 Second->Else(Loc, IfLoc);
536 /// \brief Hook called whenever an \#endif is seen.
537 void Endif(SourceLocation Loc, SourceLocation IfLoc) override {
538 First->Endif(Loc, IfLoc);
539 Second->Endif(Loc, IfLoc);
543 } // end namespace clang