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

   1 //===- VirtualFileSystem.h - Virtual File System Layer ----------*- 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 /// \file
  10 /// \brief Defines the virtual file system interface vfs::FileSystem.
  11 //===----------------------------------------------------------------------===//
  12
  13 #ifndef LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
  14 #define LLVM_CLANG_BASIC_VIRTUALFILESYSTEM_H
  15
  16 #include "clang/Basic/LLVM.h"
  17 #include "llvm/ADT/IntrusiveRefCntPtr.h"
  18 #include "llvm/ADT/Optional.h"
  19 #include "llvm/Support/ErrorOr.h"
  20 #include "llvm/Support/FileSystem.h"
  21 #include "llvm/Support/SourceMgr.h"
  22 #include "llvm/Support/raw_ostream.h"
  23 #include <utility>
  24
  25 namespace llvm {
  26 class MemoryBuffer;
  27 }
  28
  29 namespace clang {
  30 namespace vfs {
  31
  32 /// \brief The result of a \p status operation.
  33 class Status {
  34   std::string Name;
  35   llvm::sys::fs::UniqueID UID;
  36   llvm::sys::TimeValue MTime;
  37   uint32_t User;
  38   uint32_t Group;
  39   uint64_t Size;
  40   llvm::sys::fs::file_type Type;
  41   llvm::sys::fs::perms Perms;
  42
  43 public:
  44   bool IsVFSMapped; // FIXME: remove when files support multiple names
  45
  46 public:
  47   Status() : Type(llvm::sys::fs::file_type::status_error) {}
  48   Status(const llvm::sys::fs::file_status &Status);
  49   Status(StringRef Name, llvm::sys::fs::UniqueID UID,
  50          llvm::sys::TimeValue MTime, uint32_t User, uint32_t Group,
  51          uint64_t Size, llvm::sys::fs::file_type Type,
  52          llvm::sys::fs::perms Perms);
  53
  54   /// Get a copy of a Status with a different name.
  55   static Status copyWithNewName(const Status &In, StringRef NewName);
  56   static Status copyWithNewName(const llvm::sys::fs::file_status &In,
  57                                 StringRef NewName);
  58
  59   /// \brief Returns the name that should be used for this file or directory.
  60   StringRef getName() const { return Name; }
  61
  62   /// @name Status interface from llvm::sys::fs
  63   /// @{
  64   llvm::sys::fs::file_type getType() const { return Type; }
  65   llvm::sys::fs::perms getPermissions() const { return Perms; }
  66   llvm::sys::TimeValue getLastModificationTime() const { return MTime; }
  67   llvm::sys::fs::UniqueID getUniqueID() const { return UID; }
  68   uint32_t getUser() const { return User; }
  69   uint32_t getGroup() const { return Group; }
  70   uint64_t getSize() const { return Size; }
  71   /// @}
  72   /// @name Status queries
  73   /// These are static queries in llvm::sys::fs.
  74   /// @{
  75   bool equivalent(const Status &Other) const;
  76   bool isDirectory() const;
  77   bool isRegularFile() const;
  78   bool isOther() const;
  79   bool isSymlink() const;
  80   bool isStatusKnown() const;
  81   bool exists() const;
  82   /// @}
  83 };
  84
  85 /// \brief Represents an open file.
  86 class File {
  87 public:
  88   /// \brief Destroy the file after closing it (if open).
  89   /// Sub-classes should generally call close() inside their destructors.  We
  90   /// cannot do that from the base class, since close is virtual.
  91   virtual ~File();
  92   /// \brief Get the status of the file.
  93   virtual llvm::ErrorOr<Status> status() = 0;
  94   /// \brief Get the name of the file
  95   virtual llvm::ErrorOr<std::string> getName() {
  96     if (auto Status = status())
  97       return Status->getName().str();
  98     else
  99       return Status.getError();
 100   }
 101   /// \brief Get the contents of the file as a \p MemoryBuffer.
 102   virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
 103   getBuffer(const Twine &Name, int64_t FileSize = -1,
 104             bool RequiresNullTerminator = true, bool IsVolatile = false) = 0;
 105   /// \brief Closes the file.
 106   virtual std::error_code close() = 0;
 107 };
 108
 109 namespace detail {
 110 /// \brief An interface for virtual file systems to provide an iterator over the
 111 /// (non-recursive) contents of a directory.
 112 struct DirIterImpl {
 113   virtual ~DirIterImpl();
 114   /// \brief Sets \c CurrentEntry to the next entry in the directory on success,
 115   /// or returns a system-defined \c error_code.
 116   virtual std::error_code increment() = 0;
 117   Status CurrentEntry;
 118 };
 119 } // end namespace detail
 120
 121 /// \brief An input iterator over the entries in a virtual path, similar to
 122 /// llvm::sys::fs::directory_iterator.
 123 class directory_iterator {
 124   std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
 125
 126 public:
 127   directory_iterator(std::shared_ptr<detail::DirIterImpl> I)
 128       : Impl(std::move(I)) {
 129     assert(Impl.get() != nullptr && "requires non-null implementation");
 130     if (!Impl->CurrentEntry.isStatusKnown())
 131       Impl.reset(); // Normalize the end iterator to Impl == nullptr.
 132   }
 133
 134   /// \brief Construct an 'end' iterator.
 135   directory_iterator() { }
 136
 137   /// \brief Equivalent to operator++, with an error code.
 138   directory_iterator &increment(std::error_code &EC) {
 139     assert(Impl && "attempting to increment past end");
 140     EC = Impl->increment();
 141     if (EC || !Impl->CurrentEntry.isStatusKnown())
 142       Impl.reset(); // Normalize the end iterator to Impl == nullptr.
 143     return *this;
 144   }
 145
 146   const Status &operator*() const { return Impl->CurrentEntry; }
 147   const Status *operator->() const { return &Impl->CurrentEntry; }
 148
 149   bool operator==(const directory_iterator &RHS) const {
 150     if (Impl && RHS.Impl)
 151       return Impl->CurrentEntry.equivalent(RHS.Impl->CurrentEntry);
 152     return !Impl && !RHS.Impl;
 153   }
 154   bool operator!=(const directory_iterator &RHS) const {
 155     return !(*this == RHS);
 156   }
 157 };
 158
 159 class FileSystem;
 160
 161 /// \brief An input iterator over the recursive contents of a virtual path,
 162 /// similar to llvm::sys::fs::recursive_directory_iterator.
 163 class recursive_directory_iterator {
 164   typedef std::stack<directory_iterator, std::vector<directory_iterator>>
 165       IterState;
 166
 167   FileSystem *FS;
 168   std::shared_ptr<IterState> State; // Input iterator semantics on copy.
 169
 170 public:
 171   recursive_directory_iterator(FileSystem &FS, const Twine &Path,
 172                                std::error_code &EC);
 173   /// \brief Construct an 'end' iterator.
 174   recursive_directory_iterator() { }
 175
 176   /// \brief Equivalent to operator++, with an error code.
 177   recursive_directory_iterator &increment(std::error_code &EC);
 178
 179   const Status &operator*() const { return *State->top(); }
 180   const Status *operator->() const { return &*State->top(); }
 181
 182   bool operator==(const recursive_directory_iterator &Other) const {
 183     return State == Other.State; // identity
 184   }
 185   bool operator!=(const recursive_directory_iterator &RHS) const {
 186     return !(*this == RHS);
 187   }
 188   /// \brief Gets the current level. Starting path is at level 0.
 189   int level() const {
 190     assert(State->size() && "Cannot get level without any iteration state");
 191     return State->size()-1;
 192   }
 193 };
 194
 195 /// \brief The virtual file system interface.
 196 class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
 197 public:
 198   virtual ~FileSystem();
 199
 200   /// \brief Get the status of the entry at \p Path, if one exists.
 201   virtual llvm::ErrorOr<Status> status(const Twine &Path) = 0;
 202   /// \brief Get a \p File object for the file at \p Path, if one exists.
 203   virtual llvm::ErrorOr<std::unique_ptr<File>>
 204   openFileForRead(const Twine &Path) = 0;
 205
 206   /// This is a convenience method that opens a file, gets its content and then
 207   /// closes the file.
 208   llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
 209   getBufferForFile(const Twine &Name, int64_t FileSize = -1,
 210                    bool RequiresNullTerminator = true, bool IsVolatile = false);
 211
 212   /// \brief Get a directory_iterator for \p Dir.
 213   /// \note The 'end' iterator is directory_iterator().
 214   virtual directory_iterator dir_begin(const Twine &Dir,
 215                                        std::error_code &EC) = 0;
 216
 217   /// Set the working directory. This will affect all following operations on
 218   /// this file system and may propagate down for nested file systems.
 219   virtual std::error_code setCurrentWorkingDirectory(const Twine &Path) = 0;
 220   /// Get the working directory of this file system.
 221   virtual llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const = 0;
 222
 223   /// Check whether a file exists. Provided for convenience.
 224   bool exists(const Twine &Path);
 225
 226   /// Make \a Path an absolute path.
 227   ///
 228   /// Makes \a Path absolute using the current directory if it is not already.
 229   /// An empty \a Path will result in the current directory.
 230   ///
 231   /// /absolute/path   => /absolute/path
 232   /// relative/../path => <current-directory>/relative/../path
 233   ///
 234   /// \param Path A path that is modified to be an absolute path.
 235   /// \returns success if \a path has been made absolute, otherwise a
 236   ///          platform-specific error_code.
 237   std::error_code makeAbsolute(SmallVectorImpl<char> &Path) const;
 238 };
 239
 240 /// \brief Gets an \p vfs::FileSystem for the 'real' file system, as seen by
 241 /// the operating system.
 242 IntrusiveRefCntPtr<FileSystem> getRealFileSystem();
 243
 244 /// \brief A file system that allows overlaying one \p AbstractFileSystem on top
 245 /// of another.
 246 ///
 247 /// Consists of a stack of >=1 \p FileSystem objects, which are treated as being
 248 /// one merged file system. When there is a directory that exists in more than
 249 /// one file system, the \p OverlayFileSystem contains a directory containing
 250 /// the union of their contents.  The attributes (permissions, etc.) of the
 251 /// top-most (most recently added) directory are used.  When there is a file
 252 /// that exists in more than one file system, the file in the top-most file
 253 /// system overrides the other(s).
 254 class OverlayFileSystem : public FileSystem {
 255   typedef SmallVector<IntrusiveRefCntPtr<FileSystem>, 1> FileSystemList;
 256   /// \brief The stack of file systems, implemented as a list in order of
 257   /// their addition.
 258   FileSystemList FSList;
 259
 260 public:
 261   OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
 262   /// \brief Pushes a file system on top of the stack.
 263   void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
 264
 265   llvm::ErrorOr<Status> status(const Twine &Path) override;
 266   llvm::ErrorOr<std::unique_ptr<File>>
 267   openFileForRead(const Twine &Path) override;
 268   directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
 269   llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override;
 270   std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
 271
 272   typedef FileSystemList::reverse_iterator iterator;
 273
 274   /// \brief Get an iterator pointing to the most recently added file system.
 275   iterator overlays_begin() { return FSList.rbegin(); }
 276
 277   /// \brief Get an iterator pointing one-past the least recently added file
 278   /// system.
 279   iterator overlays_end() { return FSList.rend(); }
 280 };
 281
 282 namespace detail {
 283 class InMemoryDirectory;
 284 } // end namespace detail
 285
 286 /// An in-memory file system.
 287 class InMemoryFileSystem : public FileSystem {
 288   std::unique_ptr<detail::InMemoryDirectory> Root;
 289   std::string WorkingDirectory;
 290   bool UseNormalizedPaths = true;
 291
 292 public:
 293   explicit InMemoryFileSystem(bool UseNormalizedPaths = true);
 294   ~InMemoryFileSystem() override;
 295   /// Add a buffer to the VFS with a path. The VFS owns the buffer.
 296   /// \return true if the file was successfully added, false if the file already
 297   /// exists in the file system with different contents.
 298   bool addFile(const Twine &Path, time_t ModificationTime,
 299                std::unique_ptr<llvm::MemoryBuffer> Buffer);
 300   /// Add a buffer to the VFS with a path. The VFS does not own the buffer.
 301   /// \return true if the file was successfully added, false if the file already
 302   /// exists in the file system with different contents.
 303   bool addFileNoOwn(const Twine &Path, time_t ModificationTime,
 304                     llvm::MemoryBuffer *Buffer);
 305   std::string toString() const;
 306   /// Return true if this file system normalizes . and .. in paths.
 307   bool useNormalizedPaths() const { return UseNormalizedPaths; }
 308
 309   llvm::ErrorOr<Status> status(const Twine &Path) override;
 310   llvm::ErrorOr<std::unique_ptr<File>>
 311   openFileForRead(const Twine &Path) override;
 312   directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
 313   llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {
 314     return WorkingDirectory;
 315   }
 316   std::error_code setCurrentWorkingDirectory(const Twine &Path) override;
 317 };
 318
 319 /// \brief Get a globally unique ID for a virtual file or directory.
 320 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
 321
 322 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
 323 /// format.
 324 IntrusiveRefCntPtr<FileSystem>
 325 getVFSFromYAML(std::unique_ptr<llvm::MemoryBuffer> Buffer,
 326                llvm::SourceMgr::DiagHandlerTy DiagHandler,
 327                StringRef YAMLFilePath,
 328                void *DiagContext = nullptr,
 329                IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
 330
 331 struct YAMLVFSEntry {
 332   template <typename T1, typename T2> YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
 333       : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
 334   std::string VPath;
 335   std::string RPath;
 336 };
 337
 338 class YAMLVFSWriter {
 339   std::vector<YAMLVFSEntry> Mappings;
 340   Optional<bool> IsCaseSensitive;
 341   Optional<bool> IsOverlayRelative;
 342   Optional<bool> UseExternalNames;
 343   std::string OverlayDir;
 344
 345 public:
 346   YAMLVFSWriter() {}
 347   void addFileMapping(StringRef VirtualPath, StringRef RealPath);
 348   void setCaseSensitivity(bool CaseSensitive) {
 349     IsCaseSensitive = CaseSensitive;
 350   }
 351   void setUseExternalNames(bool UseExtNames) {
 352     UseExternalNames = UseExtNames;
 353   }
 354   void setOverlayDir(StringRef OverlayDirectory) {
 355     IsOverlayRelative = true;
 356     OverlayDir.assign(OverlayDirectory.str());
 357   }
 358
 359   void write(llvm::raw_ostream &OS);
 360 };
 361
 362 } // end namespace vfs
 363 } // end namespace clang
 364 #endif