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
24namespace llvm {
25class MemoryBuffer;
26}
27
28namespace clang {
29namespace vfs {
30
31/// \brief The result of a \p status operation.
32class 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
42public:
43  bool IsVFSMapped; // FIXME: remove when files support multiple names
44
45public:
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.
83class File {
84public:
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
103namespace detail {
104/// \brief An interface for virtual file systems to provide an iterator over the
105/// (non-recursive) contents of a directory.
106struct 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.
117class directory_iterator {
118  std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
119
120public:
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
152class FileSystem;
153
154/// \brief An input iterator over the recursive contents of a virtual path,
155/// similar to llvm::sys::fs::recursive_directory_iterator.
156class 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
163public:
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.
184class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
185public:
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.
210IntrusiveRefCntPtr<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).
222class 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
228public:
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.
249llvm::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.
255IntrusiveRefCntPtr<FileSystem>
256getVFSFromYAML(llvm::MemoryBuffer *Buffer,
257               llvm::SourceMgr::DiagHandlerTy DiagHandler,
258               void *DiagContext = nullptr,
259               IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
260
261struct 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
268class YAMLVFSWriter {
269  std::vector<YAMLVFSEntry> Mappings;
270  Optional<bool> IsCaseSensitive;
271
272public:
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