Home | History | Annotate | Download | only in Basic 
      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_VIRTUAL_FILE_SYSTEM_H
     14 #define LLVM_CLANG_BASIC_VIRTUAL_FILE_SYSTEM_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/raw_ostream.h"
     22 #include "llvm/Support/SourceMgr.h"
     23 
     24 namespace llvm {
     25 class MemoryBuffer;
     26 }
     27 
     28 namespace clang {
     29 namespace vfs {
     30 
     31 /// \brief The result of a \p status operation.
     32 class Status {
     33   std::string Name;
     34   llvm::sys::fs::UniqueID UID;
     35   llvm::sys::TimeValue MTime;
     36   uint32_t User;
     37   uint32_t Group;
     38   uint64_t Size;
     39   llvm::sys::fs::file_type Type;
     40   llvm::sys::fs::perms Perms;
     41 
     42 public:
     43   bool IsVFSMapped; // FIXME: remove when files support multiple names
     44 
     45 public:
     46   Status() : Type(llvm::sys::fs::file_type::status_error) {}
     47   Status(const llvm::sys::fs::file_status &Status);
     48   Status(StringRef Name, StringRef RealName, llvm::sys::fs::UniqueID UID,
     49          llvm::sys::TimeValue MTime, uint32_t User, uint32_t Group,
     50          uint64_t Size, llvm::sys::fs::file_type Type,
     51          llvm::sys::fs::perms Perms);
     52 
     53   /// \brief Returns the name that should be used for this file or directory.
     54   StringRef getName() const { return Name; }
     55   void setName(StringRef N) { Name = N; }
     56 
     57   /// @name Status interface from llvm::sys::fs
     58   /// @{
     59   llvm::sys::fs::file_type getType() const { return Type; }
     60   llvm::sys::fs::perms getPermissions() const { return Perms; }
     61   llvm::sys::TimeValue getLastModificationTime() const { return MTime; }
     62   llvm::sys::fs::UniqueID getUniqueID() const { return UID; }
     63   uint32_t getUser() const { return User; }
     64   uint32_t getGroup() const { return Group; }
     65   uint64_t getSize() const { return Size; }
     66   void setType(llvm::sys::fs::file_type v) { Type = v; }
     67   void setPermissions(llvm::sys::fs::perms p) { Perms = p; }
     68   /// @}
     69   /// @name Status queries
     70   /// These are static queries in llvm::sys::fs.
     71   /// @{
     72   bool equivalent(const Status &Other) const;
     73   bool isDirectory() const;
     74   bool isRegularFile() const;
     75   bool isOther() const;
     76   bool isSymlink() const;
     77   bool isStatusKnown() const;
     78   bool exists() const;
     79   /// @}
     80 };
     81 
     82 /// \brief Represents an open file.
     83 class File {
     84 public:
     85   /// \brief Destroy the file after closing it (if open).
     86   /// Sub-classes should generally call close() inside their destructors.  We
     87   /// cannot do that from the base class, since close is virtual.
     88   virtual ~File();
     89   /// \brief Get the status of the file.
     90   virtual llvm::ErrorOr<Status> status() = 0;
     91   /// \brief Get the contents of the file as a \p MemoryBuffer.
     92   virtual std::error_code getBuffer(const Twine &Name,
     93                                     std::unique_ptr<llvm::MemoryBuffer> &Result,
     94                                     int64_t FileSize = -1,
     95                                     bool RequiresNullTerminator = true,
     96                                     bool IsVolatile = false) = 0;
     97   /// \brief Closes the file.
     98   virtual std::error_code close() = 0;
     99   /// \brief Sets the name to use for this file.
    100   virtual void setName(StringRef Name) = 0;
    101 };
    102 
    103 namespace detail {
    104 /// \brief An interface for virtual file systems to provide an iterator over the
    105 /// (non-recursive) contents of a directory.
    106 struct DirIterImpl {
    107   virtual ~DirIterImpl();
    108   /// \brief Sets \c CurrentEntry to the next entry in the directory on success,
    109   /// or returns a system-defined \c error_code.
    110   virtual std::error_code increment() = 0;
    111   Status CurrentEntry;
    112 };
    113 } // end namespace detail
    114 
    115 /// \brief An input iterator over the entries in a virtual path, similar to
    116 /// llvm::sys::fs::directory_iterator.
    117 class directory_iterator {
    118   std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
    119 
    120 public:
    121   directory_iterator(std::shared_ptr<detail::DirIterImpl> I) : Impl(I) {
    122     assert(Impl.get() != nullptr && "requires non-null implementation");
    123     if (!Impl->CurrentEntry.isStatusKnown())
    124       Impl.reset(); // Normalize the end iterator to Impl == nullptr.
    125   }
    126 
    127   /// \brief Construct an 'end' iterator.
    128   directory_iterator() { }
    129 
    130   /// \brief Equivalent to operator++, with an error code.
    131   directory_iterator &increment(std::error_code &EC) {
    132     assert(Impl && "attempting to increment past end");
    133     EC = Impl->increment();
    134     if (EC || !Impl->CurrentEntry.isStatusKnown())
    135       Impl.reset(); // Normalize the end iterator to Impl == nullptr.
    136     return *this;
    137   }
    138 
    139   const Status &operator*() const { return Impl->CurrentEntry; }
    140   const Status *operator->() const { return &Impl->CurrentEntry; }
    141 
    142   bool operator==(const directory_iterator &RHS) const {
    143     if (Impl && RHS.Impl)
    144       return Impl->CurrentEntry.equivalent(RHS.Impl->CurrentEntry);
    145     return !Impl && !RHS.Impl;
    146   }
    147   bool operator!=(const directory_iterator &RHS) const {
    148     return !(*this == RHS);
    149   }
    150 };
    151 
    152 class FileSystem;
    153 
    154 /// \brief An input iterator over the recursive contents of a virtual path,
    155 /// similar to llvm::sys::fs::recursive_directory_iterator.
    156 class recursive_directory_iterator {
    157   typedef std::stack<directory_iterator, std::vector<directory_iterator>>
    158       IterState;
    159 
    160   FileSystem *FS;
    161   std::shared_ptr<IterState> State; // Input iterator semantics on copy.
    162 
    163 public:
    164   recursive_directory_iterator(FileSystem &FS, const Twine &Path,
    165                                std::error_code &EC);
    166   /// \brief Construct an 'end' iterator.
    167   recursive_directory_iterator() { }
    168 
    169   /// \brief Equivalent to operator++, with an error code.
    170   recursive_directory_iterator &increment(std::error_code &EC);
    171 
    172   const Status &operator*() const { return *State->top(); }
    173   const Status *operator->() const { return &*State->top(); }
    174 
    175   bool operator==(const recursive_directory_iterator &Other) const {
    176     return State == Other.State; // identity
    177   }
    178   bool operator!=(const recursive_directory_iterator &RHS) const {
    179     return !(*this == RHS);
    180   }
    181 };
    182 
    183 /// \brief The virtual file system interface.
    184 class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
    185 public:
    186   virtual ~FileSystem();
    187 
    188   /// \brief Get the status of the entry at \p Path, if one exists.
    189   virtual llvm::ErrorOr<Status> status(const Twine &Path) = 0;
    190   /// \brief Get a \p File object for the file at \p Path, if one exists.
    191   virtual std::error_code openFileForRead(const Twine &Path,
    192                                           std::unique_ptr<File> &Result) = 0;
    193 
    194   /// This is a convenience method that opens a file, gets its content and then
    195   /// closes the file.
    196   std::error_code getBufferForFile(const Twine &Name,
    197                                    std::unique_ptr<llvm::MemoryBuffer> &Result,
    198                                    int64_t FileSize = -1,
    199                                    bool RequiresNullTerminator = true,
    200                                    bool IsVolatile = false);
    201 
    202   /// \brief Get a directory_iterator for \p Dir.
    203   /// \note The 'end' iterator is directory_iterator().
    204   virtual directory_iterator dir_begin(const Twine &Dir,
    205                                        std::error_code &EC) = 0;
    206 };
    207 
    208 /// \brief Gets an \p vfs::FileSystem for the 'real' file system, as seen by
    209 /// the operating system.
    210 IntrusiveRefCntPtr<FileSystem> getRealFileSystem();
    211 
    212 /// \brief A file system that allows overlaying one \p AbstractFileSystem on top
    213 /// of another.
    214 ///
    215 /// Consists of a stack of >=1 \p FileSystem objects, which are treated as being
    216 /// one merged file system. When there is a directory that exists in more than
    217 /// one file system, the \p OverlayFileSystem contains a directory containing
    218 /// the union of their contents.  The attributes (permissions, etc.) of the
    219 /// top-most (most recently added) directory are used.  When there is a file
    220 /// that exists in more than one file system, the file in the top-most file
    221 /// system overrides the other(s).
    222 class OverlayFileSystem : public FileSystem {
    223   typedef SmallVector<IntrusiveRefCntPtr<FileSystem>, 1> FileSystemList;
    224   /// \brief The stack of file systems, implemented as a list in order of
    225   /// their addition.
    226   FileSystemList FSList;
    227 
    228 public:
    229   OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
    230   /// \brief Pushes a file system on top of the stack.
    231   void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
    232 
    233   llvm::ErrorOr<Status> status(const Twine &Path) override;
    234   std::error_code openFileForRead(const Twine &Path,
    235                                   std::unique_ptr<File> &Result) override;
    236   directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
    237 
    238   typedef FileSystemList::reverse_iterator iterator;
    239 
    240   /// \brief Get an iterator pointing to the most recently added file system.
    241   iterator overlays_begin() { return FSList.rbegin(); }
    242 
    243   /// \brief Get an iterator pointing one-past the least recently added file
    244   /// system.
    245   iterator overlays_end() { return FSList.rend(); }
    246 };
    247 
    248 /// \brief Get a globally unique ID for a virtual file or directory.
    249 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
    250 
    251 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
    252 /// format.
    253 ///
    254 /// Takes ownership of \p Buffer.
    255 IntrusiveRefCntPtr<FileSystem>
    256 getVFSFromYAML(llvm::MemoryBuffer *Buffer,
    257                llvm::SourceMgr::DiagHandlerTy DiagHandler,
    258                void *DiagContext = nullptr,
    259                IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
    260 
    261 struct YAMLVFSEntry {
    262   template <typename T1, typename T2> YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
    263       : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
    264   std::string VPath;
    265   std::string RPath;
    266 };
    267 
    268 class YAMLVFSWriter {
    269   std::vector<YAMLVFSEntry> Mappings;
    270   Optional<bool> IsCaseSensitive;
    271 
    272 public:
    273   YAMLVFSWriter() {}
    274   void addFileMapping(StringRef VirtualPath, StringRef RealPath);
    275   void setCaseSensitivity(bool CaseSensitive) {
    276     IsCaseSensitive = CaseSensitive;
    277   }
    278   void write(llvm::raw_ostream &OS);
    279 };
    280 
    281 } // end namespace vfs
    282 } // end namespace clang
    283 #endif // LLVM_CLANG_BASIC_VIRTUAL_FILE_SYSTEM_H
    284