include/clang/Lex/PPCallbacks.h

   1 //===--- PPCallbacks.h - Callbacks for Preprocessor actions -----*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 ///
  10 /// \file
  11 /// \brief Defines the PPCallbacks interface.
  12 ///
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_CLANG_LEX_PPCALLBACKS_H
  16 #define LLVM_CLANG_LEX_PPCALLBACKS_H
  17
  18 #include "clang/Basic/DiagnosticIDs.h"
  19 #include "clang/Basic/SourceLocation.h"
  20 #include "clang/Lex/DirectoryLookup.h"
  21 #include "clang/Lex/ModuleLoader.h"
  22 #include "clang/Lex/Pragma.h"
  23 #include "llvm/ADT/StringRef.h"
  24 #include <string>
  25
  26 namespace clang {
  27   class SourceLocation;
  28   class Token;
  29   class IdentifierInfo;
  30   class MacroDefinition;
  31   class MacroDirective;
  32   class MacroArgs;
  33
  34 /// \brief This interface provides a way to observe the actions of the
  35 /// preprocessor as it does its thing.
  36 ///
  37 /// Clients can define their hooks here to implement preprocessor level tools.
  38 class PPCallbacks {
  39 public:
  40   virtual ~PPCallbacks();
  41
  42   enum FileChangeReason {
  43     EnterFile, ExitFile, SystemHeaderPragma, RenameFile
  44   };
  45
  46   /// \brief Callback invoked whenever a source file is entered or exited.
  47   ///
  48   /// \param Loc Indicates the new location.
  49   /// \param PrevFID the file that was exited if \p Reason is ExitFile.
  50   virtual void FileChanged(SourceLocation Loc, FileChangeReason Reason,
  51                            SrcMgr::CharacteristicKind FileType,
  52                            FileID PrevFID = FileID()) {
  53   }
  54
  55   /// \brief Callback invoked whenever a source file is skipped as the result
  56   /// of header guard optimization.
  57   ///
  58   /// \param SkippedFile The file that is skipped instead of entering \#include
  59   ///
  60   /// \param FilenameTok The file name token in \#include "FileName" directive
  61   /// or macro expanded file name token from \#include MACRO(PARAMS) directive.
  62   /// Note that FilenameTok contains corresponding quotes/angles symbols.
  63   virtual void FileSkipped(const FileEntry &SkippedFile,
  64                            const Token &FilenameTok,
  65                            SrcMgr::CharacteristicKind FileType) {
  66   }
  67
  68   /// \brief Callback invoked whenever an inclusion directive results in a
  69   /// file-not-found error.
  70   ///
  71   /// \param FileName The name of the file being included, as written in the
  72   /// source code.
  73   ///
  74   /// \param RecoveryPath If this client indicates that it can recover from
  75   /// this missing file, the client should set this as an additional header
  76   /// search patch.
  77   ///
  78   /// \returns true to indicate that the preprocessor should attempt to recover
  79   /// by adding \p RecoveryPath as a header search path.
  80   virtual bool FileNotFound(StringRef FileName,
  81                             SmallVectorImpl<char> &RecoveryPath) {
  82     return false;
  83   }
  84
  85   /// \brief Callback invoked whenever an inclusion directive of
  86   /// any kind (\c \#include, \c \#import, etc.) has been processed, regardless
  87   /// of whether the inclusion will actually result in an inclusion.
  88   ///
  89   /// \param HashLoc The location of the '#' that starts the inclusion
  90   /// directive.
  91   ///
  92   /// \param IncludeTok The token that indicates the kind of inclusion
  93   /// directive, e.g., 'include' or 'import'.
  94   ///
  95   /// \param FileName The name of the file being included, as written in the
  96   /// source code.
  97   ///
  98   /// \param IsAngled Whether the file name was enclosed in angle brackets;
  99   /// otherwise, it was enclosed in quotes.
 100   ///
 101   /// \param FilenameRange The character range of the quotes or angle brackets
 102   /// for the written file name.
 103   ///
 104   /// \param File The actual file that may be included by this inclusion
 105   /// directive.
 106   ///
 107   /// \param SearchPath Contains the search path which was used to find the file
 108   /// in the file system. If the file was found via an absolute include path,
 109   /// SearchPath will be empty. For framework includes, the SearchPath and
 110   /// RelativePath will be split up. For example, if an include of "Some/Some.h"
 111   /// is found via the framework path
 112   /// "path/to/Frameworks/Some.framework/Headers/Some.h", SearchPath will be
 113   /// "path/to/Frameworks/Some.framework/Headers" and RelativePath will be
 114   /// "Some.h".
 115   ///
 116   /// \param RelativePath The path relative to SearchPath, at which the include
 117   /// file was found. This is equal to FileName except for framework includes.
 118   ///
 119   /// \param Imported The module, whenever an inclusion directive was
 120   /// automatically turned into a module import or null otherwise.
 121   ///
 122   virtual void InclusionDirective(SourceLocation HashLoc,
 123                                   const Token &IncludeTok,
 124                                   StringRef FileName,
 125                                   bool IsAngled,
 126                                   CharSourceRange FilenameRange,
 127                                   const FileEntry *File,
 128                                   StringRef SearchPath,
 129                                   StringRef RelativePath,
 130                                   const Module *Imported) {
 131   }
 132
 133   /// \brief Callback invoked whenever there was an explicit module-import
 134   /// syntax.
 135   ///
 136   /// \param ImportLoc The location of import directive token.
 137   ///
 138   /// \param Path The identifiers (and their locations) of the module
 139   /// "path", e.g., "std.vector" would be split into "std" and "vector".
 140   ///
 141   /// \param Imported The imported module; can be null if importing failed.
 142   ///
 143   virtual void moduleImport(SourceLocation ImportLoc,
 144                             ModuleIdPath Path,
 145                             const Module *Imported) {
 146   }
 147
 148   /// \brief Callback invoked when the end of the main file is reached.
 149   ///
 150   /// No subsequent callbacks will be made.
 151   virtual void EndOfMainFile() {
 152   }
 153
 154   /// \brief Callback invoked when a \#ident or \#sccs directive is read.
 155   /// \param Loc The location of the directive.
 156   /// \param str The text of the directive.
 157   ///
 158   virtual void Ident(SourceLocation Loc, const std::string &str) {
 159   }
 160
 161   /// \brief Callback invoked when start reading any pragma directive.
 162   virtual void PragmaDirective(SourceLocation Loc,
 163                                PragmaIntroducerKind Introducer) {
 164   }
 165
 166   /// \brief Callback invoked when a \#pragma comment directive is read.
 167   virtual void PragmaComment(SourceLocation Loc, const IdentifierInfo *Kind,
 168                              const std::string &Str) {
 169   }
 170
 171   /// \brief Callback invoked when a \#pragma detect_mismatch directive is
 172   /// read.
 173   virtual void PragmaDetectMismatch(SourceLocation Loc,
 174                                     const std::string &Name,
 175                                     const std::string &Value) {
 176   }
 177
 178   /// \brief Callback invoked when a \#pragma clang __debug directive is read.
 179   /// \param Loc The location of the debug directive.
 180   /// \param DebugType The identifier following __debug.
 181   virtual void PragmaDebug(SourceLocation Loc, StringRef DebugType) {
 182   }
 183
 184   /// \brief Determines the kind of \#pragma invoking a call to PragmaMessage.
 185   enum PragmaMessageKind {
 186     /// \brief \#pragma message has been invoked.
 187     PMK_Message,
 188
 189     /// \brief \#pragma GCC warning has been invoked.
 190     PMK_Warning,
 191
 192     /// \brief \#pragma GCC error has been invoked.
 193     PMK_Error
 194   };
 195
 196   /// \brief Callback invoked when a \#pragma message directive is read.
 197   /// \param Loc The location of the message directive.
 198   /// \param Namespace The namespace of the message directive.
 199   /// \param Kind The type of the message directive.
 200   /// \param Str The text of the message directive.
 201   virtual void PragmaMessage(SourceLocation Loc, StringRef Namespace,
 202                              PragmaMessageKind Kind, StringRef Str) {
 203   }
 204
 205   /// \brief Callback invoked when a \#pragma gcc dianostic push directive
 206   /// is read.
 207   virtual void PragmaDiagnosticPush(SourceLocation Loc,
 208                                     StringRef Namespace) {
 209   }
 210
 211   /// \brief Callback invoked when a \#pragma gcc dianostic pop directive
 212   /// is read.
 213   virtual void PragmaDiagnosticPop(SourceLocation Loc,
 214                                    StringRef Namespace) {
 215   }
 216
 217   /// \brief Callback invoked when a \#pragma gcc dianostic directive is read.
 218   virtual void PragmaDiagnostic(SourceLocation Loc, StringRef Namespace,
 219                                 diag::Severity mapping, StringRef Str) {}
 220
 221   /// \brief Called when an OpenCL extension is either disabled or
 222   /// enabled with a pragma.
 223   virtual void PragmaOpenCLExtension(SourceLocation NameLoc,
 224                                      const IdentifierInfo *Name,
 225                                      SourceLocation StateLoc, unsigned State) {
 226   }
 227
 228   /// \brief Callback invoked when a \#pragma warning directive is read.
 229   virtual void PragmaWarning(SourceLocation Loc, StringRef WarningSpec,
 230                              ArrayRef<int> Ids) {
 231   }
 232
 233   /// \brief Callback invoked when a \#pragma warning(push) directive is read.
 234   virtual void PragmaWarningPush(SourceLocation Loc, int Level) {
 235   }
 236
 237   /// \brief Callback invoked when a \#pragma warning(pop) directive is read.
 238   virtual void PragmaWarningPop(SourceLocation Loc) {
 239   }
 240
 241   /// \brief Called by Preprocessor::HandleMacroExpandedIdentifier when a
 242   /// macro invocation is found.
 243   virtual void MacroExpands(const Token &MacroNameTok,
 244                             const MacroDefinition &MD, SourceRange Range,
 245                             const MacroArgs *Args) {}
 246
 247   /// \brief Hook called whenever a macro definition is seen.
 248   virtual void MacroDefined(const Token &MacroNameTok,
 249                             const MacroDirective *MD) {
 250   }
 251
 252   /// \brief Hook called whenever a macro \#undef is seen.
 253   ///
 254   /// MD is released immediately following this callback.
 255   virtual void MacroUndefined(const Token &MacroNameTok,
 256                               const MacroDefinition &MD) {
 257   }
 258
 259   /// \brief Hook called whenever the 'defined' operator is seen.
 260   /// \param MD The MacroDirective if the name was a macro, null otherwise.
 261   virtual void Defined(const Token &MacroNameTok, const MacroDefinition &MD,
 262                        SourceRange Range) {
 263   }
 264
 265   /// \brief Hook called when a source range is skipped.
 266   /// \param Range The SourceRange that was skipped. The range begins at the
 267   /// \#if/\#else directive and ends after the \#endif/\#else directive.
 268   virtual void SourceRangeSkipped(SourceRange Range) {
 269   }
 270
 271   enum ConditionValueKind {
 272     CVK_NotEvaluated, CVK_False, CVK_True
 273   };
 274
 275   /// \brief Hook called whenever an \#if is seen.
 276   /// \param Loc the source location of the directive.
 277   /// \param ConditionRange The SourceRange of the expression being tested.
 278   /// \param ConditionValue The evaluated value of the condition.
 279   ///
 280   // FIXME: better to pass in a list (or tree!) of Tokens.
 281   virtual void If(SourceLocation Loc, SourceRange ConditionRange,
 282                   ConditionValueKind ConditionValue) {
 283   }
 284
 285   /// \brief Hook called whenever an \#elif is seen.
 286   /// \param Loc the source location of the directive.
 287   /// \param ConditionRange The SourceRange of the expression being tested.
 288   /// \param ConditionValue The evaluated value of the condition.
 289   /// \param IfLoc the source location of the \#if/\#ifdef/\#ifndef directive.
 290   // FIXME: better to pass in a list (or tree!) of Tokens.
 291   virtual void Elif(SourceLocation Loc, SourceRange ConditionRange,
 292                     ConditionValueKind ConditionValue, SourceLocation IfLoc) {
 293   }
 294
 295   /// \brief Hook called whenever an \#ifdef is seen.
 296   /// \param Loc the source location of the directive.
 297   /// \param MacroNameTok Information on the token being tested.
 298   /// \param MD The MacroDefinition if the name was a macro, null otherwise.
 299   virtual void Ifdef(SourceLocation Loc, const Token &MacroNameTok,
 300                      const MacroDefinition &MD) {
 301   }
 302
 303   /// \brief Hook called whenever an \#ifndef is seen.
 304   /// \param Loc the source location of the directive.
 305   /// \param MacroNameTok Information on the token being tested.
 306   /// \param MD The MacroDefiniton if the name was a macro, null otherwise.
 307   virtual void Ifndef(SourceLocation Loc, const Token &MacroNameTok,
 308                       const MacroDefinition &MD) {
 309   }
 310
 311   /// \brief Hook called whenever an \#else is seen.
 312   /// \param Loc the source location of the directive.
 313   /// \param IfLoc the source location of the \#if/\#ifdef/\#ifndef directive.
 314   virtual void Else(SourceLocation Loc, SourceLocation IfLoc) {
 315   }
 316
 317   /// \brief Hook called whenever an \#endif is seen.
 318   /// \param Loc the source location of the directive.
 319   /// \param IfLoc the source location of the \#if/\#ifdef/\#ifndef directive.
 320   virtual void Endif(SourceLocation Loc, SourceLocation IfLoc) {
 321   }
 322 };
 323
 324 /// \brief Simple wrapper class for chaining callbacks.
 325 class PPChainedCallbacks : public PPCallbacks {
 326   virtual void anchor();
 327   std::unique_ptr<PPCallbacks> First, Second;
 328
 329 public:
 330   PPChainedCallbacks(std::unique_ptr<PPCallbacks> _First,
 331                      std::unique_ptr<PPCallbacks> _Second)
 332     : First(std::move(_First)), Second(std::move(_Second)) {}
 333
 334   void FileChanged(SourceLocation Loc, FileChangeReason Reason,
 335                    SrcMgr::CharacteristicKind FileType,
 336                    FileID PrevFID) override {
 337     First->FileChanged(Loc, Reason, FileType, PrevFID);
 338     Second->FileChanged(Loc, Reason, FileType, PrevFID);
 339   }
 340
 341   void FileSkipped(const FileEntry &SkippedFile,
 342                    const Token &FilenameTok,
 343                    SrcMgr::CharacteristicKind FileType) override {
 344     First->FileSkipped(SkippedFile, FilenameTok, FileType);
 345     Second->FileSkipped(SkippedFile, FilenameTok, FileType);
 346   }
 347
 348   bool FileNotFound(StringRef FileName,
 349                     SmallVectorImpl<char> &RecoveryPath) override {
 350     return First->FileNotFound(FileName, RecoveryPath) ||
 351            Second->FileNotFound(FileName, RecoveryPath);
 352   }
 353
 354   void InclusionDirective(SourceLocation HashLoc, const Token &IncludeTok,
 355                           StringRef FileName, bool IsAngled,
 356                           CharSourceRange FilenameRange, const FileEntry *File,
 357                           StringRef SearchPath, StringRef RelativePath,
 358                           const Module *Imported) override {
 359     First->InclusionDirective(HashLoc, IncludeTok, FileName, IsAngled,
 360                               FilenameRange, File, SearchPath, RelativePath,
 361                               Imported);
 362     Second->InclusionDirective(HashLoc, IncludeTok, FileName, IsAngled,
 363                                FilenameRange, File, SearchPath, RelativePath,
 364                                Imported);
 365   }
 366
 367   void moduleImport(SourceLocation ImportLoc, ModuleIdPath Path,
 368                     const Module *Imported) override {
 369     First->moduleImport(ImportLoc, Path, Imported);
 370     Second->moduleImport(ImportLoc, Path, Imported);
 371   }
 372
 373   void EndOfMainFile() override {
 374     First->EndOfMainFile();
 375     Second->EndOfMainFile();
 376   }
 377
 378   void Ident(SourceLocation Loc, const std::string &str) override {
 379     First->Ident(Loc, str);
 380     Second->Ident(Loc, str);
 381   }
 382
 383   void PragmaComment(SourceLocation Loc, const IdentifierInfo *Kind,
 384                      const std::string &Str) override {
 385     First->PragmaComment(Loc, Kind, Str);
 386     Second->PragmaComment(Loc, Kind, Str);
 387   }
 388
 389   void PragmaDetectMismatch(SourceLocation Loc, const std::string &Name,
 390                             const std::string &Value) override {
 391     First->PragmaDetectMismatch(Loc, Name, Value);
 392     Second->PragmaDetectMismatch(Loc, Name, Value);
 393   }
 394
 395   void PragmaMessage(SourceLocation Loc, StringRef Namespace,
 396                      PragmaMessageKind Kind, StringRef Str) override {
 397     First->PragmaMessage(Loc, Namespace, Kind, Str);
 398     Second->PragmaMessage(Loc, Namespace, Kind, Str);
 399   }
 400
 401   void PragmaDiagnosticPush(SourceLocation Loc, StringRef Namespace) override {
 402     First->PragmaDiagnosticPush(Loc, Namespace);
 403     Second->PragmaDiagnosticPush(Loc, Namespace);
 404   }
 405
 406   void PragmaDiagnosticPop(SourceLocation Loc, StringRef Namespace) override {
 407     First->PragmaDiagnosticPop(Loc, Namespace);
 408     Second->PragmaDiagnosticPop(Loc, Namespace);
 409   }
 410
 411   void PragmaDiagnostic(SourceLocation Loc, StringRef Namespace,
 412                         diag::Severity mapping, StringRef Str) override {
 413     First->PragmaDiagnostic(Loc, Namespace, mapping, Str);
 414     Second->PragmaDiagnostic(Loc, Namespace, mapping, Str);
 415   }
 416
 417   void PragmaOpenCLExtension(SourceLocation NameLoc, const IdentifierInfo *Name,
 418                              SourceLocation StateLoc, unsigned State) override {
 419     First->PragmaOpenCLExtension(NameLoc, Name, StateLoc, State);
 420     Second->PragmaOpenCLExtension(NameLoc, Name, StateLoc, State);
 421   }
 422
 423   void PragmaWarning(SourceLocation Loc, StringRef WarningSpec,
 424                      ArrayRef<int> Ids) override {
 425     First->PragmaWarning(Loc, WarningSpec, Ids);
 426     Second->PragmaWarning(Loc, WarningSpec, Ids);
 427   }
 428
 429   void PragmaWarningPush(SourceLocation Loc, int Level) override {
 430     First->PragmaWarningPush(Loc, Level);
 431     Second->PragmaWarningPush(Loc, Level);
 432   }
 433
 434   void PragmaWarningPop(SourceLocation Loc) override {
 435     First->PragmaWarningPop(Loc);
 436     Second->PragmaWarningPop(Loc);
 437   }
 438
 439   void MacroExpands(const Token &MacroNameTok, const MacroDefinition &MD,
 440                     SourceRange Range, const MacroArgs *Args) override {
 441     First->MacroExpands(MacroNameTok, MD, Range, Args);
 442     Second->MacroExpands(MacroNameTok, MD, Range, Args);
 443   }
 444
 445   void MacroDefined(const Token &MacroNameTok, const MacroDirective *MD) override {
 446     First->MacroDefined(MacroNameTok, MD);
 447     Second->MacroDefined(MacroNameTok, MD);
 448   }
 449
 450   void MacroUndefined(const Token &MacroNameTok,
 451                       const MacroDefinition &MD) override {
 452     First->MacroUndefined(MacroNameTok, MD);
 453     Second->MacroUndefined(MacroNameTok, MD);
 454   }
 455
 456   void Defined(const Token &MacroNameTok, const MacroDefinition &MD,
 457                SourceRange Range) override {
 458     First->Defined(MacroNameTok, MD, Range);
 459     Second->Defined(MacroNameTok, MD, Range);
 460   }
 461
 462   void SourceRangeSkipped(SourceRange Range) override {
 463     First->SourceRangeSkipped(Range);
 464     Second->SourceRangeSkipped(Range);
 465   }
 466
 467   /// \brief Hook called whenever an \#if is seen.
 468   void If(SourceLocation Loc, SourceRange ConditionRange,
 469           ConditionValueKind ConditionValue) override {
 470     First->If(Loc, ConditionRange, ConditionValue);
 471     Second->If(Loc, ConditionRange, ConditionValue);
 472   }
 473
 474   /// \brief Hook called whenever an \#elif is seen.
 475   void Elif(SourceLocation Loc, SourceRange ConditionRange,
 476             ConditionValueKind ConditionValue, SourceLocation IfLoc) override {
 477     First->Elif(Loc, ConditionRange, ConditionValue, IfLoc);
 478     Second->Elif(Loc, ConditionRange, ConditionValue, IfLoc);
 479   }
 480
 481   /// \brief Hook called whenever an \#ifdef is seen.
 482   void Ifdef(SourceLocation Loc, const Token &MacroNameTok,
 483              const MacroDefinition &MD) override {
 484     First->Ifdef(Loc, MacroNameTok, MD);
 485     Second->Ifdef(Loc, MacroNameTok, MD);
 486   }
 487
 488   /// \brief Hook called whenever an \#ifndef is seen.
 489   void Ifndef(SourceLocation Loc, const Token &MacroNameTok,
 490               const MacroDefinition &MD) override {
 491     First->Ifndef(Loc, MacroNameTok, MD);
 492     Second->Ifndef(Loc, MacroNameTok, MD);
 493   }
 494
 495   /// \brief Hook called whenever an \#else is seen.
 496   void Else(SourceLocation Loc, SourceLocation IfLoc) override {
 497     First->Else(Loc, IfLoc);
 498     Second->Else(Loc, IfLoc);
 499   }
 500
 501   /// \brief Hook called whenever an \#endif is seen.
 502   void Endif(SourceLocation Loc, SourceLocation IfLoc) override {
 503     First->Endif(Loc, IfLoc);
 504     Second->Endif(Loc, IfLoc);
 505   }
 506 };
 507
 508 }  // end namespace clang
 509
 510 #endif