contrib/llvm/tools/clang/include/clang/Basic/SourceManager.h

   1 //===--- SourceManager.h - Track and cache source files ---------*- 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 //  This file defines the SourceManager interface.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_CLANG_SOURCEMANAGER_H
  15 #define LLVM_CLANG_SOURCEMANAGER_H
  16
  17 #include "clang/Basic/SourceLocation.h"
  18 #include "llvm/Support/Allocator.h"
  19 #include "llvm/Support/DataTypes.h"
  20 #include "llvm/ADT/PointerIntPair.h"
  21 #include "llvm/ADT/PointerUnion.h"
  22 #include "llvm/ADT/IntrusiveRefCntPtr.h"
  23 #include "llvm/ADT/DenseMap.h"
  24 #include "llvm/Support/MemoryBuffer.h"
  25 #include <vector>
  26 #include <cassert>
  27
  28 namespace llvm {
  29 class StringRef;
  30 }
  31
  32 namespace clang {
  33
  34 class Diagnostic;
  35 class SourceManager;
  36 class FileManager;
  37 class FileEntry;
  38 class LineTableInfo;
  39 class LangOptions;
  40
  41 /// SrcMgr - Public enums and private classes that are part of the
  42 /// SourceManager implementation.
  43 ///
  44 namespace SrcMgr {
  45   /// CharacteristicKind - This is used to represent whether a file or directory
  46   /// holds normal user code, system code, or system code which is implicitly
  47   /// 'extern "C"' in C++ mode.  Entire directories can be tagged with this
  48   /// (this is maintained by DirectoryLookup and friends) as can specific
  49   /// FileIDInfos when a #pragma system_header is seen or various other cases.
  50   ///
  51   enum CharacteristicKind {
  52     C_User, C_System, C_ExternCSystem
  53   };
  54
  55   /// ContentCache - One instance of this struct is kept for every file
  56   /// loaded or used.  This object owns the MemoryBuffer object.
  57   class ContentCache {
  58     enum CCFlags {
  59       /// \brief Whether the buffer is invalid.
  60       InvalidFlag = 0x01,
  61       /// \brief Whether the buffer should not be freed on destruction.
  62       DoNotFreeFlag = 0x02
  63     };
  64
  65     /// Buffer - The actual buffer containing the characters from the input
  66     /// file.  This is owned by the ContentCache object.
  67     /// The bits indicate indicates whether the buffer is invalid.
  68     mutable llvm::PointerIntPair<const llvm::MemoryBuffer *, 2> Buffer;
  69
  70   public:
  71     /// Reference to the file entry representing this ContentCache.
  72     /// This reference does not own the FileEntry object.
  73     /// It is possible for this to be NULL if
  74     /// the ContentCache encapsulates an imaginary text buffer.
  75     const FileEntry *OrigEntry;
  76
  77     /// \brief References the file which the contents were actually loaded from.
  78     /// Can be different from 'Entry' if we overridden the contents of one file
  79     /// with the contents of another file.
  80     const FileEntry *ContentsEntry;
  81
  82     /// SourceLineCache - A bump pointer allocated array of offsets for each
  83     /// source line.  This is lazily computed.  This is owned by the
  84     /// SourceManager BumpPointerAllocator object.
  85     unsigned *SourceLineCache;
  86
  87     /// NumLines - The number of lines in this ContentCache.  This is only valid
  88     /// if SourceLineCache is non-null.
  89     unsigned NumLines;
  90
  91     /// getBuffer - Returns the memory buffer for the associated content.
  92     ///
  93     /// \param Diag Object through which diagnostics will be emitted if the
  94     /// buffer cannot be retrieved.
  95     ///
  96     /// \param Loc If specified, is the location that invalid file diagnostics
  97     ///     will be emitted at.
  98     ///
  99     /// \param Invalid If non-NULL, will be set \c true if an error occurred.
 100     const llvm::MemoryBuffer *getBuffer(Diagnostic &Diag,
 101                                         const SourceManager &SM,
 102                                         SourceLocation Loc = SourceLocation(),
 103                                         bool *Invalid = 0) const;
 104
 105     /// getSize - Returns the size of the content encapsulated by this
 106     ///  ContentCache. This can be the size of the source file or the size of an
 107     ///  arbitrary scratch buffer.  If the ContentCache encapsulates a source
 108     ///  file this size is retrieved from the file's FileEntry.
 109     unsigned getSize() const;
 110
 111     /// getSizeBytesMapped - Returns the number of bytes actually mapped for
 112     ///  this ContentCache.  This can be 0 if the MemBuffer was not actually
 113     ///  instantiated.
 114     unsigned getSizeBytesMapped() const;
 115
 116     /// Returns the kind of memory used to back the memory buffer for
 117     /// this content cache.  This is used for performance analysis.
 118     llvm::MemoryBuffer::BufferKind getMemoryBufferKind() const;
 119
 120     void setBuffer(const llvm::MemoryBuffer *B) {
 121       assert(!Buffer.getPointer() && "MemoryBuffer already set.");
 122       Buffer.setPointer(B);
 123       Buffer.setInt(false);
 124     }
 125
 126     /// \brief Get the underlying buffer, returning NULL if the buffer is not
 127     /// yet available.
 128     const llvm::MemoryBuffer *getRawBuffer() const {
 129       return Buffer.getPointer();
 130     }
 131
 132     /// \brief Replace the existing buffer (which will be deleted)
 133     /// with the given buffer.
 134     void replaceBuffer(const llvm::MemoryBuffer *B, bool DoNotFree = false);
 135
 136     /// \brief Determine whether the buffer itself is invalid.
 137     bool isBufferInvalid() const {
 138       return Buffer.getInt() & InvalidFlag;
 139     }
 140
 141     /// \brief Determine whether the buffer should be freed.
 142     bool shouldFreeBuffer() const {
 143       return (Buffer.getInt() & DoNotFreeFlag) == 0;
 144     }
 145
 146     ContentCache(const FileEntry *Ent = 0)
 147       : Buffer(0, false), OrigEntry(Ent), ContentsEntry(Ent),
 148         SourceLineCache(0), NumLines(0) {}
 149
 150     ContentCache(const FileEntry *Ent, const FileEntry *contentEnt)
 151       : Buffer(0, false), OrigEntry(Ent), ContentsEntry(contentEnt),
 152         SourceLineCache(0), NumLines(0) {}
 153
 154     ~ContentCache();
 155
 156     /// The copy ctor does not allow copies where source object has either
 157     ///  a non-NULL Buffer or SourceLineCache.  Ownership of allocated memory
 158     ///  is not transferred, so this is a logical error.
 159     ContentCache(const ContentCache &RHS)
 160       : Buffer(0, false), SourceLineCache(0)
 161     {
 162       OrigEntry = RHS.OrigEntry;
 163       ContentsEntry = RHS.ContentsEntry;
 164
 165       assert (RHS.Buffer.getPointer() == 0 && RHS.SourceLineCache == 0
 166               && "Passed ContentCache object cannot own a buffer.");
 167
 168       NumLines = RHS.NumLines;
 169     }
 170
 171   private:
 172     // Disable assignments.
 173     ContentCache &operator=(const ContentCache& RHS);
 174   };
 175
 176   /// FileInfo - Information about a FileID, basically just the logical file
 177   /// that it represents and include stack information.
 178   ///
 179   /// Each FileInfo has include stack information, indicating where it came
 180   /// from.  This information encodes the #include chain that a token was
 181   /// instantiated from.  The main include file has an invalid IncludeLoc.
 182   ///
 183   /// FileInfos contain a "ContentCache *", with the contents of the file.
 184   ///
 185   class FileInfo {
 186     /// IncludeLoc - The location of the #include that brought in this file.
 187     /// This is an invalid SLOC for the main file (top of the #include chain).
 188     unsigned IncludeLoc;  // Really a SourceLocation
 189
 190     /// Data - This contains the ContentCache* and the bits indicating the
 191     /// characteristic of the file and whether it has #line info, all bitmangled
 192     /// together.
 193     uintptr_t Data;
 194   public:
 195     /// get - Return a FileInfo object.
 196     static FileInfo get(SourceLocation IL, const ContentCache *Con,
 197                         CharacteristicKind FileCharacter) {
 198       FileInfo X;
 199       X.IncludeLoc = IL.getRawEncoding();
 200       X.Data = (uintptr_t)Con;
 201       assert((X.Data & 7) == 0 &&"ContentCache pointer insufficiently aligned");
 202       assert((unsigned)FileCharacter < 4 && "invalid file character");
 203       X.Data |= (unsigned)FileCharacter;
 204       return X;
 205     }
 206
 207     SourceLocation getIncludeLoc() const {
 208       return SourceLocation::getFromRawEncoding(IncludeLoc);
 209     }
 210     const ContentCache* getContentCache() const {
 211       return reinterpret_cast<const ContentCache*>(Data & ~7UL);
 212     }
 213
 214     /// getCharacteristic - Return whether this is a system header or not.
 215     CharacteristicKind getFileCharacteristic() const {
 216       return (CharacteristicKind)(Data & 3);
 217     }
 218
 219     /// hasLineDirectives - Return true if this FileID has #line directives in
 220     /// it.
 221     bool hasLineDirectives() const { return (Data & 4) != 0; }
 222
 223     /// setHasLineDirectives - Set the flag that indicates that this FileID has
 224     /// line table entries associated with it.
 225     void setHasLineDirectives() {
 226       Data |= 4;
 227     }
 228   };
 229
 230   /// InstantiationInfo - Each InstantiationInfo encodes the Instantiation
 231   /// location - where the token was ultimately instantiated, and the
 232   /// SpellingLoc - where the actual character data for the token came from.
 233   class InstantiationInfo {
 234      // Really these are all SourceLocations.
 235
 236     /// SpellingLoc - Where the spelling for the token can be found.
 237     unsigned SpellingLoc;
 238
 239     /// InstantiationLocStart/InstantiationLocEnd - In a macro expansion, these
 240     /// indicate the start and end of the instantiation.  In object-like macros,
 241     /// these will be the same.  In a function-like macro instantiation, the
 242     /// start will be the identifier and the end will be the ')'.  Finally, in
 243     /// macro-argument instantitions, the end will be 'SourceLocation()', an
 244     /// invalid location.
 245     unsigned InstantiationLocStart, InstantiationLocEnd;
 246
 247   public:
 248     SourceLocation getSpellingLoc() const {
 249       return SourceLocation::getFromRawEncoding(SpellingLoc);
 250     }
 251     SourceLocation getInstantiationLocStart() const {
 252       return SourceLocation::getFromRawEncoding(InstantiationLocStart);
 253     }
 254     SourceLocation getInstantiationLocEnd() const {
 255       SourceLocation EndLoc =
 256         SourceLocation::getFromRawEncoding(InstantiationLocEnd);
 257       return EndLoc.isInvalid() ? getInstantiationLocStart() : EndLoc;
 258     }
 259
 260     std::pair<SourceLocation,SourceLocation> getInstantiationLocRange() const {
 261       return std::make_pair(getInstantiationLocStart(),
 262                             getInstantiationLocEnd());
 263     }
 264
 265     bool isMacroArgInstantiation() const {
 266       // Note that this needs to return false for default constructed objects.
 267       return getInstantiationLocStart().isValid() &&
 268         SourceLocation::getFromRawEncoding(InstantiationLocEnd).isInvalid();
 269     }
 270
 271     /// create - Return a InstantiationInfo for an expansion. ILStart and
 272     /// ILEnd specify the instantiation range (where the macro is expanded),
 273     /// and SL specifies the spelling location (where the characters from the
 274     /// token come from). All three can refer to normal File SLocs or
 275     /// instantiation locations.
 276     static InstantiationInfo create(SourceLocation SL,
 277                                     SourceLocation ILStart,
 278                                     SourceLocation ILEnd) {
 279       InstantiationInfo X;
 280       X.SpellingLoc = SL.getRawEncoding();
 281       X.InstantiationLocStart = ILStart.getRawEncoding();
 282       X.InstantiationLocEnd = ILEnd.getRawEncoding();
 283       return X;
 284     }
 285
 286     /// createForMacroArg - Return a special InstantiationInfo for the
 287     /// expansion of a macro argument into a function-like macro's body. IL
 288     /// specifies the instantiation location (where the macro is expanded).
 289     /// This doesn't need to be a range because a macro is always instantiated
 290     /// at a macro parameter reference, and macro parameters are always exactly
 291     /// one token. SL specifies the spelling location (where the characters
 292     /// from the token come from). IL and SL can both refer to normal File
 293     /// SLocs or instantiation locations.
 294     ///
 295     /// Given the code:
 296     /// \code
 297     ///   #define F(x) f(x)
 298     ///   F(42);
 299     /// \endcode
 300     ///
 301     /// When expanding '\c F(42)', the '\c x' would call this with an SL
 302     /// pointing at '\c 42' anad an IL pointing at its location in the
 303     /// definition of '\c F'.
 304     static InstantiationInfo createForMacroArg(SourceLocation SL,
 305                                                SourceLocation IL) {
 306       // We store an intentionally invalid source location for the end of the
 307       // instantiation range to mark that this is a macro argument instantation
 308       // rather than a normal one.
 309       return create(SL, IL, SourceLocation());
 310     }
 311   };
 312
 313   /// SLocEntry - This is a discriminated union of FileInfo and
 314   /// InstantiationInfo.  SourceManager keeps an array of these objects, and
 315   /// they are uniquely identified by the FileID datatype.
 316   class SLocEntry {
 317     unsigned Offset;   // low bit is set for instantiation info.
 318     union {
 319       FileInfo File;
 320       InstantiationInfo Instantiation;
 321     };
 322   public:
 323     unsigned getOffset() const { return Offset >> 1; }
 324
 325     bool isInstantiation() const { return Offset & 1; }
 326     bool isFile() const { return !isInstantiation(); }
 327
 328     const FileInfo &getFile() const {
 329       assert(isFile() && "Not a file SLocEntry!");
 330       return File;
 331     }
 332
 333     const InstantiationInfo &getInstantiation() const {
 334       assert(isInstantiation() && "Not an instantiation SLocEntry!");
 335       return Instantiation;
 336     }
 337
 338     static SLocEntry get(unsigned Offset, const FileInfo &FI) {
 339       SLocEntry E;
 340       E.Offset = Offset << 1;
 341       E.File = FI;
 342       return E;
 343     }
 344
 345     static SLocEntry get(unsigned Offset, const InstantiationInfo &II) {
 346       SLocEntry E;
 347       E.Offset = (Offset << 1) | 1;
 348       E.Instantiation = II;
 349       return E;
 350     }
 351   };
 352 }  // end SrcMgr namespace.
 353
 354 /// \brief External source of source location entries.
 355 class ExternalSLocEntrySource {
 356 public:
 357   virtual ~ExternalSLocEntrySource();
 358
 359   /// \brief Read the source location entry with index ID.
 360   ///
 361   /// \returns true if an error occurred that prevented the source-location
 362   /// entry from being loaded.
 363   virtual bool ReadSLocEntry(unsigned ID) = 0;
 364 };
 365
 366
 367 /// IsBeforeInTranslationUnitCache - This class holds the cache used by
 368 /// isBeforeInTranslationUnit.  The cache structure is complex enough to be
 369 /// worth breaking out of SourceManager.
 370 class IsBeforeInTranslationUnitCache {
 371   /// L/R QueryFID - These are the FID's of the cached query.  If these match up
 372   /// with a subsequent query, the result can be reused.
 373   FileID LQueryFID, RQueryFID;
 374
 375   /// CommonFID - This is the file found in common between the two #include
 376   /// traces.  It is the nearest common ancestor of the #include tree.
 377   FileID CommonFID;
 378
 379   /// L/R CommonOffset - This is the offset of the previous query in CommonFID.
 380   /// Usually, this represents the location of the #include for QueryFID, but if
 381   /// LQueryFID is a parent of RQueryFID (or vise versa) then these can be a
 382   /// random token in the parent.
 383   unsigned LCommonOffset, RCommonOffset;
 384 public:
 385
 386   /// isCacheValid - Return true if the currently cached values match up with
 387   /// the specified LHS/RHS query.  If not, we can't use the cache.
 388   bool isCacheValid(FileID LHS, FileID RHS) const {
 389     return LQueryFID == LHS && RQueryFID == RHS;
 390   }
 391
 392   /// getCachedResult - If the cache is valid, compute the result given the
 393   /// specified offsets in the LHS/RHS FID's.
 394   bool getCachedResult(unsigned LOffset, unsigned ROffset) const {
 395     // If one of the query files is the common file, use the offset.  Otherwise,
 396     // use the #include loc in the common file.
 397     if (LQueryFID != CommonFID) LOffset = LCommonOffset;
 398     if (RQueryFID != CommonFID) ROffset = RCommonOffset;
 399     return LOffset < ROffset;
 400   }
 401
 402   // Set up a new query.
 403   void setQueryFIDs(FileID LHS, FileID RHS) {
 404     LQueryFID = LHS;
 405     RQueryFID = RHS;
 406   }
 407
 408   void setCommonLoc(FileID commonFID, unsigned lCommonOffset,
 409                     unsigned rCommonOffset) {
 410     CommonFID = commonFID;
 411     LCommonOffset = lCommonOffset;
 412     RCommonOffset = rCommonOffset;
 413   }
 414
 415 };
 416
 417 /// SourceManager - This file handles loading and caching of source files into
 418 /// memory.  This object owns the MemoryBuffer objects for all of the loaded
 419 /// files and assigns unique FileID's for each unique #include chain.
 420 ///
 421 /// The SourceManager can be queried for information about SourceLocation
 422 /// objects, turning them into either spelling or instantiation locations.
 423 /// Spelling locations represent where the bytes corresponding to a token came
 424 /// from and instantiation locations represent where the location is in the
 425 /// user's view.  In the case of a macro expansion, for example, the spelling
 426 /// location indicates  where the expanded token came from and the instantiation
 427 /// location specifies where it was expanded.
 428 class SourceManager : public llvm::RefCountedBase<SourceManager> {
 429   /// \brief Diagnostic object.
 430   Diagnostic &Diag;
 431
 432   FileManager &FileMgr;
 433
 434   mutable llvm::BumpPtrAllocator ContentCacheAlloc;
 435
 436   /// FileInfos - Memoized information about all of the files tracked by this
 437   /// SourceManager.  This set allows us to merge ContentCache entries based
 438   /// on their FileEntry*.  All ContentCache objects will thus have unique,
 439   /// non-null, FileEntry pointers.
 440   llvm::DenseMap<const FileEntry*, SrcMgr::ContentCache*> FileInfos;
 441
 442   /// \brief True if the ContentCache for files that are overriden by other
 443   /// files, should report the original file name. Defaults to true.
 444   bool OverridenFilesKeepOriginalName;
 445
 446   /// \brief Files that have been overriden with the contents from another file.
 447   llvm::DenseMap<const FileEntry *, const FileEntry *> OverriddenFiles;
 448
 449   /// MemBufferInfos - Information about various memory buffers that we have
 450   /// read in.  All FileEntry* within the stored ContentCache objects are NULL,
 451   /// as they do not refer to a file.
 452   std::vector<SrcMgr::ContentCache*> MemBufferInfos;
 453
 454   /// SLocEntryTable - This is an array of SLocEntry's that we have created.
 455   /// FileID is an index into this vector.  This array is sorted by the offset.
 456   std::vector<SrcMgr::SLocEntry> SLocEntryTable;
 457   /// NextOffset - This is the next available offset that a new SLocEntry can
 458   /// start at.  It is SLocEntryTable.back().getOffset()+size of back() entry.
 459   unsigned NextOffset;
 460
 461   /// \brief If source location entries are being lazily loaded from
 462   /// an external source, this vector indicates whether the Ith source
 463   /// location entry has already been loaded from the external storage.
 464   std::vector<bool> SLocEntryLoaded;
 465
 466   /// \brief An external source for source location entries.
 467   ExternalSLocEntrySource *ExternalSLocEntries;
 468
 469   /// LastFileIDLookup - This is a one-entry cache to speed up getFileID.
 470   /// LastFileIDLookup records the last FileID looked up or created, because it
 471   /// is very common to look up many tokens from the same file.
 472   mutable FileID LastFileIDLookup;
 473
 474   /// LineTable - This holds information for #line directives.  It is referenced
 475   /// by indices from SLocEntryTable.
 476   LineTableInfo *LineTable;
 477
 478   /// LastLineNo - These ivars serve as a cache used in the getLineNumber
 479   /// method which is used to speedup getLineNumber calls to nearby locations.
 480   mutable FileID LastLineNoFileIDQuery;
 481   mutable SrcMgr::ContentCache *LastLineNoContentCache;
 482   mutable unsigned LastLineNoFilePos;
 483   mutable unsigned LastLineNoResult;
 484
 485   /// MainFileID - The file ID for the main source file of the translation unit.
 486   FileID MainFileID;
 487
 488   // Statistics for -print-stats.
 489   mutable unsigned NumLinearScans, NumBinaryProbes;
 490
 491   // Cache results for the isBeforeInTranslationUnit method.
 492   mutable IsBeforeInTranslationUnitCache IsBeforeInTUCache;
 493
 494   // Cache for the "fake" buffer used for error-recovery purposes.
 495   mutable llvm::MemoryBuffer *FakeBufferForRecovery;
 496
 497   // SourceManager doesn't support copy construction.
 498   explicit SourceManager(const SourceManager&);
 499   void operator=(const SourceManager&);
 500 public:
 501   SourceManager(Diagnostic &Diag, FileManager &FileMgr);
 502   ~SourceManager();
 503
 504   void clearIDTables();
 505
 506   Diagnostic &getDiagnostics() const { return Diag; }
 507
 508   FileManager &getFileManager() const { return FileMgr; }
 509
 510   /// \brief Set true if the SourceManager should report the original file name
 511   /// for contents of files that were overriden by other files.Defaults to true.
 512   void setOverridenFilesKeepOriginalName(bool value) {
 513     OverridenFilesKeepOriginalName = value;
 514   }
 515
 516   //===--------------------------------------------------------------------===//
 517   // MainFileID creation and querying methods.
 518   //===--------------------------------------------------------------------===//
 519
 520   /// getMainFileID - Returns the FileID of the main source file.
 521   FileID getMainFileID() const { return MainFileID; }
 522
 523   /// createMainFileID - Create the FileID for the main source file.
 524   FileID createMainFileID(const FileEntry *SourceFile) {
 525     assert(MainFileID.isInvalid() && "MainFileID already set!");
 526     MainFileID = createFileID(SourceFile, SourceLocation(), SrcMgr::C_User);
 527     return MainFileID;
 528   }
 529
 530   /// \brief Set the file ID for the precompiled preamble, which is also the
 531   /// main file.
 532   void SetPreambleFileID(FileID Preamble) {
 533     assert(MainFileID.isInvalid() && "MainFileID already set!");
 534     MainFileID = Preamble;
 535   }
 536
 537   //===--------------------------------------------------------------------===//
 538   // Methods to create new FileID's and instantiations.
 539   //===--------------------------------------------------------------------===//
 540
 541   /// createFileID - Create a new FileID that represents the specified file
 542   /// being #included from the specified IncludePosition.  This translates NULL
 543   /// into standard input.
 544   /// PreallocateID should be non-zero to specify which pre-allocated,
 545   /// lazily computed source location is being filled in by this operation.
 546   FileID createFileID(const FileEntry *SourceFile, SourceLocation IncludePos,
 547                       SrcMgr::CharacteristicKind FileCharacter,
 548                       unsigned PreallocatedID = 0,
 549                       unsigned Offset = 0) {
 550     const SrcMgr::ContentCache *IR = getOrCreateContentCache(SourceFile);
 551     assert(IR && "getOrCreateContentCache() cannot return NULL");
 552     return createFileID(IR, IncludePos, FileCharacter, PreallocatedID, Offset);
 553   }
 554
 555   /// createFileIDForMemBuffer - Create a new FileID that represents the
 556   /// specified memory buffer.  This does no caching of the buffer and takes
 557   /// ownership of the MemoryBuffer, so only pass a MemoryBuffer to this once.
 558   FileID createFileIDForMemBuffer(const llvm::MemoryBuffer *Buffer,
 559                                   unsigned PreallocatedID = 0,
 560                                   unsigned Offset = 0) {
 561     return createFileID(createMemBufferContentCache(Buffer), SourceLocation(),
 562                         SrcMgr::C_User, PreallocatedID, Offset);
 563   }
 564
 565   /// createMainFileIDForMembuffer - Create the FileID for a memory buffer
 566   ///  that will represent the FileID for the main source.  One example
 567   ///  of when this would be used is when the main source is read from STDIN.
 568   FileID createMainFileIDForMemBuffer(const llvm::MemoryBuffer *Buffer) {
 569     assert(MainFileID.isInvalid() && "MainFileID already set!");
 570     MainFileID = createFileIDForMemBuffer(Buffer);
 571     return MainFileID;
 572   }
 573
 574   /// createMacroArgInstantiationLoc - Return a new SourceLocation that encodes
 575   /// the fact that a token from SpellingLoc should actually be referenced from
 576   /// InstantiationLoc, and that it represents the instantiation of a macro
 577   /// argument into the function-like macro body.
 578   SourceLocation createMacroArgInstantiationLoc(SourceLocation Loc,
 579                                                 SourceLocation InstantiationLoc,
 580                                                 unsigned TokLength);
 581
 582   /// createInstantiationLoc - Return a new SourceLocation that encodes the fact
 583   /// that a token from SpellingLoc should actually be referenced from
 584   /// InstantiationLoc.
 585   SourceLocation createInstantiationLoc(SourceLocation Loc,
 586                                         SourceLocation InstantiationLocStart,
 587                                         SourceLocation InstantiationLocEnd,
 588                                         unsigned TokLength,
 589                                         unsigned PreallocatedID = 0,
 590                                         unsigned Offset = 0);
 591
 592   /// \brief Retrieve the memory buffer associated with the given file.
 593   ///
 594   /// \param Invalid If non-NULL, will be set \c true if an error
 595   /// occurs while retrieving the memory buffer.
 596   const llvm::MemoryBuffer *getMemoryBufferForFile(const FileEntry *File,
 597                                                    bool *Invalid = 0);
 598
 599   /// \brief Override the contents of the given source file by providing an
 600   /// already-allocated buffer.
 601   ///
 602   /// \param SourceFile the source file whose contents will be overriden.
 603   ///
 604   /// \param Buffer the memory buffer whose contents will be used as the
 605   /// data in the given source file.
 606   ///
 607   /// \param DoNotFree If true, then the buffer will not be freed when the
 608   /// source manager is destroyed.
 609   void overrideFileContents(const FileEntry *SourceFile,
 610                             const llvm::MemoryBuffer *Buffer,
 611                             bool DoNotFree = false);
 612
 613   /// \brief Override the the given source file with another one.
 614   ///
 615   /// \param SourceFile the source file which will be overriden.
 616   ///
 617   /// \param NewFile the file whose contents will be used as the
 618   /// data instead of the contents of the given source file.
 619   void overrideFileContents(const FileEntry *SourceFile,
 620                             const FileEntry *NewFile);
 621
 622   //===--------------------------------------------------------------------===//
 623   // FileID manipulation methods.
 624   //===--------------------------------------------------------------------===//
 625
 626   /// getBuffer - Return the buffer for the specified FileID. If there is an
 627   /// error opening this buffer the first time, this manufactures a temporary
 628   /// buffer and returns a non-empty error string.
 629   const llvm::MemoryBuffer *getBuffer(FileID FID, SourceLocation Loc,
 630                                       bool *Invalid = 0) const {
 631     bool MyInvalid = false;
 632     const SrcMgr::SLocEntry &Entry = getSLocEntry(FID, &MyInvalid);
 633     if (MyInvalid || !Entry.isFile()) {
 634       if (Invalid)
 635         *Invalid = true;
 636
 637       return getFakeBufferForRecovery();
 638     }
 639
 640     return Entry.getFile().getContentCache()->getBuffer(Diag, *this, Loc,
 641                                                         Invalid);
 642   }
 643
 644   const llvm::MemoryBuffer *getBuffer(FileID FID, bool *Invalid = 0) const {
 645     bool MyInvalid = false;
 646     const SrcMgr::SLocEntry &Entry = getSLocEntry(FID, &MyInvalid);
 647     if (MyInvalid || !Entry.isFile()) {
 648       if (Invalid)
 649         *Invalid = true;
 650
 651       return getFakeBufferForRecovery();
 652     }
 653
 654     return Entry.getFile().getContentCache()->getBuffer(Diag, *this,
 655                                                         SourceLocation(),
 656                                                         Invalid);
 657   }
 658
 659   /// getFileEntryForID - Returns the FileEntry record for the provided FileID.
 660   const FileEntry *getFileEntryForID(FileID FID) const {
 661     bool MyInvalid = false;
 662     const SrcMgr::SLocEntry &Entry = getSLocEntry(FID, &MyInvalid);
 663     if (MyInvalid || !Entry.isFile())
 664       return 0;
 665
 666     return Entry.getFile().getContentCache()->OrigEntry;
 667   }
 668
 669   /// Returns the FileEntry record for the provided SLocEntry.
 670   const FileEntry *getFileEntryForSLocEntry(const SrcMgr::SLocEntry &sloc) const
 671   {
 672     return sloc.getFile().getContentCache()->OrigEntry;
 673   }
 674
 675   /// getBufferData - Return a StringRef to the source buffer data for the
 676   /// specified FileID.
 677   ///
 678   /// \param FID The file ID whose contents will be returned.
 679   /// \param Invalid If non-NULL, will be set true if an error occurred.
 680   llvm::StringRef getBufferData(FileID FID, bool *Invalid = 0) const;
 681
 682
 683   //===--------------------------------------------------------------------===//
 684   // SourceLocation manipulation methods.
 685   //===--------------------------------------------------------------------===//
 686
 687   /// getFileID - Return the FileID for a SourceLocation.  This is a very
 688   /// hot method that is used for all SourceManager queries that start with a
 689   /// SourceLocation object.  It is responsible for finding the entry in
 690   /// SLocEntryTable which contains the specified location.
 691   ///
 692   FileID getFileID(SourceLocation SpellingLoc) const {
 693     unsigned SLocOffset = SpellingLoc.getOffset();
 694
 695     // If our one-entry cache covers this offset, just return it.
 696     if (isOffsetInFileID(LastFileIDLookup, SLocOffset))
 697       return LastFileIDLookup;
 698
 699     return getFileIDSlow(SLocOffset);
 700   }
 701
 702   /// getLocForStartOfFile - Return the source location corresponding to the
 703   /// first byte of the specified file.
 704   SourceLocation getLocForStartOfFile(FileID FID) const {
 705     assert(FID.ID < SLocEntryTable.size() && "FileID out of range");
 706     bool Invalid = false;
 707     const SrcMgr::SLocEntry &Entry = getSLocEntry(FID, &Invalid);
 708     if (Invalid || !Entry.isFile())
 709       return SourceLocation();
 710
 711     unsigned FileOffset = Entry.getOffset();
 712     return SourceLocation::getFileLoc(FileOffset);
 713   }
 714
 715   /// getInstantiationLoc - Given a SourceLocation object, return the
 716   /// instantiation location referenced by the ID.
 717   SourceLocation getInstantiationLoc(SourceLocation Loc) const {
 718     // Handle the non-mapped case inline, defer to out of line code to handle
 719     // instantiations.
 720     if (Loc.isFileID()) return Loc;
 721     return getInstantiationLocSlowCase(Loc);
 722   }
 723
 724   /// getImmediateInstantiationRange - Loc is required to be an instantiation
 725   /// location.  Return the start/end of the instantiation information.
 726   std::pair<SourceLocation,SourceLocation>
 727   getImmediateInstantiationRange(SourceLocation Loc) const;
 728
 729   /// getInstantiationRange - Given a SourceLocation object, return the
 730   /// range of tokens covered by the instantiation in the ultimate file.
 731   std::pair<SourceLocation,SourceLocation>
 732   getInstantiationRange(SourceLocation Loc) const;
 733
 734
 735   /// getSpellingLoc - Given a SourceLocation object, return the spelling
 736   /// location referenced by the ID.  This is the place where the characters
 737   /// that make up the lexed token can be found.
 738   SourceLocation getSpellingLoc(SourceLocation Loc) const {
 739     // Handle the non-mapped case inline, defer to out of line code to handle
 740     // instantiations.
 741     if (Loc.isFileID()) return Loc;
 742     return getSpellingLocSlowCase(Loc);
 743   }
 744
 745   /// getImmediateSpellingLoc - Given a SourceLocation object, return the
 746   /// spelling location referenced by the ID.  This is the first level down
 747   /// towards the place where the characters that make up the lexed token can be
 748   /// found.  This should not generally be used by clients.
 749   SourceLocation getImmediateSpellingLoc(SourceLocation Loc) const;
 750
 751   /// getDecomposedLoc - Decompose the specified location into a raw FileID +
 752   /// Offset pair.  The first element is the FileID, the second is the
 753   /// offset from the start of the buffer of the location.
 754   std::pair<FileID, unsigned> getDecomposedLoc(SourceLocation Loc) const {
 755     FileID FID = getFileID(Loc);
 756     return std::make_pair(FID, Loc.getOffset()-getSLocEntry(FID).getOffset());
 757   }
 758
 759   /// getDecomposedInstantiationLoc - Decompose the specified location into a
 760   /// raw FileID + Offset pair.  If the location is an instantiation record,
 761   /// walk through it until we find the final location instantiated.
 762   std::pair<FileID, unsigned>
 763   getDecomposedInstantiationLoc(SourceLocation Loc) const {
 764     FileID FID = getFileID(Loc);
 765     const SrcMgr::SLocEntry *E = &getSLocEntry(FID);
 766
 767     unsigned Offset = Loc.getOffset()-E->getOffset();
 768     if (Loc.isFileID())
 769       return std::make_pair(FID, Offset);
 770
 771     return getDecomposedInstantiationLocSlowCase(E);
 772   }
 773
 774   /// getDecomposedSpellingLoc - Decompose the specified location into a raw
 775   /// FileID + Offset pair.  If the location is an instantiation record, walk
 776   /// through it until we find its spelling record.
 777   std::pair<FileID, unsigned>
 778   getDecomposedSpellingLoc(SourceLocation Loc) const {
 779     FileID FID = getFileID(Loc);
 780     const SrcMgr::SLocEntry *E = &getSLocEntry(FID);
 781
 782     unsigned Offset = Loc.getOffset()-E->getOffset();
 783     if (Loc.isFileID())
 784       return std::make_pair(FID, Offset);
 785     return getDecomposedSpellingLocSlowCase(E, Offset);
 786   }
 787
 788   /// getFileOffset - This method returns the offset from the start
 789   /// of the file that the specified SourceLocation represents. This is not very
 790   /// meaningful for a macro ID.
 791   unsigned getFileOffset(SourceLocation SpellingLoc) const {
 792     return getDecomposedLoc(SpellingLoc).second;
 793   }
 794
 795   /// isMacroArgInstantiation - This method tests whether the given source
 796   /// location represents a macro argument's instantiation into the
 797   /// function-like macro definition. Such source locations only appear inside
 798   /// of the instantiation locations representing where a particular
 799   /// function-like macro was expanded.
 800   bool isMacroArgInstantiation(SourceLocation Loc) const;
 801
 802   //===--------------------------------------------------------------------===//
 803   // Queries about the code at a SourceLocation.
 804   //===--------------------------------------------------------------------===//
 805
 806   /// getCharacterData - Return a pointer to the start of the specified location
 807   /// in the appropriate spelling MemoryBuffer.
 808   ///
 809   /// \param Invalid If non-NULL, will be set \c true if an error occurs.
 810   const char *getCharacterData(SourceLocation SL, bool *Invalid = 0) const;
 811
 812   /// getColumnNumber - Return the column # for the specified file position.
 813   /// This is significantly cheaper to compute than the line number.  This
 814   /// returns zero if the column number isn't known.  This may only be called on
 815   /// a file sloc, so you must choose a spelling or instantiation location
 816   /// before calling this method.
 817   unsigned getColumnNumber(FileID FID, unsigned FilePos,
 818                            bool *Invalid = 0) const;
 819   unsigned getSpellingColumnNumber(SourceLocation Loc, bool *Invalid = 0) const;
 820   unsigned getInstantiationColumnNumber(SourceLocation Loc,
 821                                         bool *Invalid = 0) const;
 822   unsigned getPresumedColumnNumber(SourceLocation Loc, bool *Invalid = 0) const;
 823
 824
 825   /// getLineNumber - Given a SourceLocation, return the spelling line number
 826   /// for the position indicated.  This requires building and caching a table of
 827   /// line offsets for the MemoryBuffer, so this is not cheap: use only when
 828   /// about to emit a diagnostic.
 829   unsigned getLineNumber(FileID FID, unsigned FilePos, bool *Invalid = 0) const;
 830   unsigned getSpellingLineNumber(SourceLocation Loc, bool *Invalid = 0) const;
 831   unsigned getInstantiationLineNumber(SourceLocation Loc,
 832                                       bool *Invalid = 0) const;
 833   unsigned getPresumedLineNumber(SourceLocation Loc, bool *Invalid = 0) const;
 834
 835   /// Return the filename or buffer identifier of the buffer the location is in.
 836   /// Note that this name does not respect #line directives.  Use getPresumedLoc
 837   /// for normal clients.
 838   const char *getBufferName(SourceLocation Loc, bool *Invalid = 0) const;
 839
 840   /// getFileCharacteristic - return the file characteristic of the specified
 841   /// source location, indicating whether this is a normal file, a system
 842   /// header, or an "implicit extern C" system header.
 843   ///
 844   /// This state can be modified with flags on GNU linemarker directives like:
 845   ///   # 4 "foo.h" 3
 846   /// which changes all source locations in the current file after that to be
 847   /// considered to be from a system header.
 848   SrcMgr::CharacteristicKind getFileCharacteristic(SourceLocation Loc) const;
 849
 850   /// getPresumedLoc - This method returns the "presumed" location of a
 851   /// SourceLocation specifies.  A "presumed location" can be modified by #line
 852   /// or GNU line marker directives.  This provides a view on the data that a
 853   /// user should see in diagnostics, for example.
 854   ///
 855   /// Note that a presumed location is always given as the instantiation point
 856   /// of an instantiation location, not at the spelling location.
 857   ///
 858   /// \returns The presumed location of the specified SourceLocation. If the
 859   /// presumed location cannot be calculate (e.g., because \p Loc is invalid
 860   /// or the file containing \p Loc has changed on disk), returns an invalid
 861   /// presumed location.
 862   PresumedLoc getPresumedLoc(SourceLocation Loc) const;
 863
 864   /// isFromSameFile - Returns true if both SourceLocations correspond to
 865   ///  the same file.
 866   bool isFromSameFile(SourceLocation Loc1, SourceLocation Loc2) const {
 867     return getFileID(Loc1) == getFileID(Loc2);
 868   }
 869
 870   /// isFromMainFile - Returns true if the file of provided SourceLocation is
 871   ///   the main file.
 872   bool isFromMainFile(SourceLocation Loc) const {
 873     return getFileID(Loc) == getMainFileID();
 874   }
 875
 876   /// isInSystemHeader - Returns if a SourceLocation is in a system header.
 877   bool isInSystemHeader(SourceLocation Loc) const {
 878     return getFileCharacteristic(Loc) != SrcMgr::C_User;
 879   }
 880
 881   /// isInExternCSystemHeader - Returns if a SourceLocation is in an "extern C"
 882   /// system header.
 883   bool isInExternCSystemHeader(SourceLocation Loc) const {
 884     return getFileCharacteristic(Loc) == SrcMgr::C_ExternCSystem;
 885   }
 886
 887   /// \brief Given a specific chunk of a FileID (FileID with offset+length),
 888   /// returns true if \arg Loc is inside that chunk and sets relative offset
 889   /// (offset of \arg Loc from beginning of chunk) to \arg relativeOffset.
 890   bool isInFileID(SourceLocation Loc,
 891                   FileID FID, unsigned offset, unsigned length,
 892                   unsigned *relativeOffset = 0) const {
 893     assert(!FID.isInvalid());
 894     if (Loc.isInvalid())
 895       return false;
 896
 897     unsigned start = getSLocEntry(FID).getOffset() + offset;
 898     unsigned end = start + length;
 899
 900 #ifndef NDEBUG
 901     // Make sure offset/length describe a chunk inside the given FileID.
 902     unsigned NextOffset;
 903     if (FID.ID+1 == SLocEntryTable.size())
 904       NextOffset = getNextOffset();
 905     else
 906       NextOffset = getSLocEntry(FID.ID+1).getOffset();
 907     assert(start < NextOffset);
 908     assert(end   < NextOffset);
 909 #endif
 910
 911     if (Loc.getOffset() >= start && Loc.getOffset() < end) {
 912       if (relativeOffset)
 913         *relativeOffset = Loc.getOffset() - start;
 914       return true;
 915     }
 916
 917     return false;
 918   }
 919
 920   //===--------------------------------------------------------------------===//
 921   // Line Table Manipulation Routines
 922   //===--------------------------------------------------------------------===//
 923
 924   /// getLineTableFilenameID - Return the uniqued ID for the specified filename.
 925   ///
 926   unsigned getLineTableFilenameID(llvm::StringRef Str);
 927
 928   /// AddLineNote - Add a line note to the line table for the FileID and offset
 929   /// specified by Loc.  If FilenameID is -1, it is considered to be
 930   /// unspecified.
 931   void AddLineNote(SourceLocation Loc, unsigned LineNo, int FilenameID);
 932   void AddLineNote(SourceLocation Loc, unsigned LineNo, int FilenameID,
 933                    bool IsFileEntry, bool IsFileExit,
 934                    bool IsSystemHeader, bool IsExternCHeader);
 935
 936   /// \brief Determine if the source manager has a line table.
 937   bool hasLineTable() const { return LineTable != 0; }
 938
 939   /// \brief Retrieve the stored line table.
 940   LineTableInfo &getLineTable();
 941
 942   //===--------------------------------------------------------------------===//
 943   // Queries for performance analysis.
 944   //===--------------------------------------------------------------------===//
 945
 946   /// Return the total amount of physical memory allocated by the
 947   /// ContentCache allocator.
 948   size_t getContentCacheSize() const {
 949     return ContentCacheAlloc.getTotalMemory();
 950   }
 951
 952   struct MemoryBufferSizes {
 953     const size_t malloc_bytes;
 954     const size_t mmap_bytes;
 955
 956     MemoryBufferSizes(size_t malloc_bytes, size_t mmap_bytes)
 957       : malloc_bytes(malloc_bytes), mmap_bytes(mmap_bytes) {}
 958   };
 959
 960   /// Return the amount of memory used by memory buffers, breaking down
 961   /// by heap-backed versus mmap'ed memory.
 962   MemoryBufferSizes getMemoryBufferSizes() const;
 963
 964   //===--------------------------------------------------------------------===//
 965   // Other miscellaneous methods.
 966   //===--------------------------------------------------------------------===//
 967
 968   /// \brief Get the source location for the given file:line:col triplet.
 969   ///
 970   /// If the source file is included multiple times, the source location will
 971   /// be based upon the first inclusion.
 972   SourceLocation getLocation(const FileEntry *SourceFile,
 973                              unsigned Line, unsigned Col);
 974
 975   /// \brief Determines the order of 2 source locations in the translation unit.
 976   ///
 977   /// \returns true if LHS source location comes before RHS, false otherwise.
 978   bool isBeforeInTranslationUnit(SourceLocation LHS, SourceLocation RHS) const;
 979
 980   /// \brief Determines the order of 2 source locations in the "source location
 981   /// address space".
 982   static bool isBeforeInSourceLocationOffset(SourceLocation LHS,
 983                                              SourceLocation RHS) {
 984     return isBeforeInSourceLocationOffset(LHS, RHS.getOffset());
 985   }
 986
 987   /// \brief Determines the order of a source location and a source location
 988   /// offset in the "source location address space".
 989   static bool isBeforeInSourceLocationOffset(SourceLocation LHS, unsigned RHS) {
 990     return LHS.getOffset() < RHS;
 991   }
 992
 993   // Iterators over FileInfos.
 994   typedef llvm::DenseMap<const FileEntry*, SrcMgr::ContentCache*>
 995       ::const_iterator fileinfo_iterator;
 996   fileinfo_iterator fileinfo_begin() const { return FileInfos.begin(); }
 997   fileinfo_iterator fileinfo_end() const { return FileInfos.end(); }
 998   bool hasFileInfo(const FileEntry *File) const {
 999     return FileInfos.find(File) != FileInfos.end();
1000   }
1001
1002   /// PrintStats - Print statistics to stderr.
1003   ///
1004   void PrintStats() const;
1005
1006   unsigned sloc_entry_size() const { return SLocEntryTable.size(); }
1007
1008   // FIXME: Exposing this is a little gross; what we want is a good way
1009   //  to iterate the entries that were not defined in an AST file (or
1010   //  any other external source).
1011   unsigned sloc_loaded_entry_size() const { return SLocEntryLoaded.size(); }
1012
1013   const SrcMgr::SLocEntry &getSLocEntry(unsigned ID, bool *Invalid = 0) const {
1014     assert(ID < SLocEntryTable.size() && "Invalid id");
1015     // If we haven't loaded this source-location entry from the external source
1016     // yet, do so now.
1017     if (ExternalSLocEntries &&
1018         ID < SLocEntryLoaded.size() &&
1019         !SLocEntryLoaded[ID] &&
1020         ExternalSLocEntries->ReadSLocEntry(ID) &&
1021         Invalid)
1022       *Invalid = true;
1023
1024     return SLocEntryTable[ID];
1025   }
1026
1027   const SrcMgr::SLocEntry &getSLocEntry(FileID FID, bool *Invalid = 0) const {
1028     return getSLocEntry(FID.ID, Invalid);
1029   }
1030
1031   unsigned getNextOffset() const { return NextOffset; }
1032
1033   /// \brief Preallocate some number of source location entries, which
1034   /// will be loaded as needed from the given external source.
1035   void PreallocateSLocEntries(ExternalSLocEntrySource *Source,
1036                               unsigned NumSLocEntries,
1037                               unsigned NextOffset);
1038
1039   /// \brief Clear out any preallocated source location entries that
1040   /// haven't already been loaded.
1041   void ClearPreallocatedSLocEntries();
1042
1043 private:
1044   const llvm::MemoryBuffer *getFakeBufferForRecovery() const;
1045
1046   /// createInstantiationLoc - Implements the common elements of storing an
1047   /// instantiation info struct into the SLocEntry table and producing a source
1048   /// location that refers to it.
1049   SourceLocation createInstantiationLocImpl(const SrcMgr::InstantiationInfo &II,
1050                                             unsigned TokLength,
1051                                             unsigned PreallocatedID = 0,
1052                                             unsigned Offset = 0);
1053
1054   /// isOffsetInFileID - Return true if the specified FileID contains the
1055   /// specified SourceLocation offset.  This is a very hot method.
1056   inline bool isOffsetInFileID(FileID FID, unsigned SLocOffset) const {
1057     const SrcMgr::SLocEntry &Entry = getSLocEntry(FID);
1058     // If the entry is after the offset, it can't contain it.
1059     if (SLocOffset < Entry.getOffset()) return false;
1060
1061     // If this is the last entry than it does.  Otherwise, the entry after it
1062     // has to not include it.
1063     if (FID.ID+1 == SLocEntryTable.size()) return true;
1064
1065     return SLocOffset < getSLocEntry(FileID::get(FID.ID+1)).getOffset();
1066   }
1067
1068   /// createFileID - Create a new fileID for the specified ContentCache and
1069   ///  include position.  This works regardless of whether the ContentCache
1070   ///  corresponds to a file or some other input source.
1071   FileID createFileID(const SrcMgr::ContentCache* File,
1072                       SourceLocation IncludePos,
1073                       SrcMgr::CharacteristicKind DirCharacter,
1074                       unsigned PreallocatedID = 0,
1075                       unsigned Offset = 0);
1076
1077   const SrcMgr::ContentCache *
1078     getOrCreateContentCache(const FileEntry *SourceFile);
1079
1080   /// createMemBufferContentCache - Create a new ContentCache for the specified
1081   ///  memory buffer.
1082   const SrcMgr::ContentCache*
1083   createMemBufferContentCache(const llvm::MemoryBuffer *Buf);
1084
1085   FileID getFileIDSlow(unsigned SLocOffset) const;
1086
1087   SourceLocation getInstantiationLocSlowCase(SourceLocation Loc) const;
1088   SourceLocation getSpellingLocSlowCase(SourceLocation Loc) const;
1089
1090   std::pair<FileID, unsigned>
1091   getDecomposedInstantiationLocSlowCase(const SrcMgr::SLocEntry *E) const;
1092   std::pair<FileID, unsigned>
1093   getDecomposedSpellingLocSlowCase(const SrcMgr::SLocEntry *E,
1094                                    unsigned Offset) const;
1095 };
1096
1097
1098 }  // end namespace clang
1099
1100 #endif