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