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