Subversion Repositories QNX 8.QNX8 LLVM/Clang compiler suite

//===- VirtualFileSystem.h - Virtual File System Layer ----------*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

//

/// \file

/// Defines the virtual file system interface vfs::FileSystem.

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_SUPPORT_VIRTUALFILESYSTEM_H

#define LLVM_SUPPORT_VIRTUALFILESYSTEM_H

#include "llvm/ADT/IntrusiveRefCntPtr.h"

#include "llvm/ADT/SmallVector.h"

#include "llvm/ADT/StringRef.h"

#include "llvm/ADT/STLFunctionalExtras.h"

#include "llvm/Support/Chrono.h"

#include "llvm/Support/ErrorOr.h"

#include "llvm/Support/Errc.h"

#include "llvm/Support/FileSystem.h"

#include "llvm/Support/Path.h"

#include "llvm/Support/SourceMgr.h"

#include <cassert>

#include <cstdint>

#include <ctime>

#include <memory>

#include <optional>

#include <stack>

#include <string>

#include <system_error>

#include <utility>

#include <vector>

namespace llvm {

class MemoryBuffer;

class MemoryBufferRef;

class Twine;

namespace vfs {

/// The result of a \p status operation.

class Status {

  std::string Name;

  llvm::sys::fs::UniqueID UID;

  llvm::sys::TimePoint<> MTime;

  uint32_t User;

  uint32_t Group;

  uint64_t Size;

  llvm::sys::fs::file_type Type = llvm::sys::fs::file_type::status_error;

  llvm::sys::fs::perms Perms;

public:

  // FIXME: remove when files support multiple names

  bool IsVFSMapped = false;

  /// Whether this entity has an external path different from the virtual path,

  /// and the external path is exposed by leaking it through the abstraction.

  /// For example, a RedirectingFileSystem will set this for paths where

  /// UseExternalName is true.

  ///

  /// FIXME: Currently the external path is exposed by replacing the virtual

  /// path in this Status object. Instead, we should leave the path in the

  /// Status intact (matching the requested virtual path) - see

  /// FileManager::getFileRef for how how we plan to fix this.

  bool ExposesExternalVFSPath = false;

  Status() = default;

  Status(const llvm::sys::fs::file_status &Status);

  Status(const Twine &Name, llvm::sys::fs::UniqueID UID,

         llvm::sys::TimePoint<> MTime, uint32_t User, uint32_t Group,

         uint64_t Size, llvm::sys::fs::file_type Type,

         llvm::sys::fs::perms Perms);

  /// Get a copy of a Status with a different size.

  static Status copyWithNewSize(const Status &In, uint64_t NewSize);

  /// Get a copy of a Status with a different name.

  static Status copyWithNewName(const Status &In, const Twine &NewName);

  static Status copyWithNewName(const llvm::sys::fs::file_status &In,

                                const Twine &NewName);

  /// Returns the name that should be used for this file or directory.

  StringRef getName() const { return Name; }

  /// @name Status interface from llvm::sys::fs

  /// @{

  llvm::sys::fs::file_type getType() const { return Type; }

  llvm::sys::fs::perms getPermissions() const { return Perms; }

  llvm::sys::TimePoint<> getLastModificationTime() const { return MTime; }

  llvm::sys::fs::UniqueID getUniqueID() const { return UID; }

  uint32_t getUser() const { return User; }

  uint32_t getGroup() const { return Group; }

  uint64_t getSize() const { return Size; }

  /// @}

  /// @name Status queries

  /// These are static queries in llvm::sys::fs.

  /// @{

  bool equivalent(const Status &Other) const;

  bool isDirectory() const;

  bool isRegularFile() const;

  bool isOther() const;

  bool isSymlink() const;

  bool isStatusKnown() const;

  bool exists() const;

  /// @}

};

/// Represents an open file.

class File {

public:

  /// Destroy the file after closing it (if open).

  /// Sub-classes should generally call close() inside their destructors.  We

  /// cannot do that from the base class, since close is virtual.

  virtual ~File();

  /// Get the status of the file.

  virtual llvm::ErrorOr<Status> status() = 0;

  /// Get the name of the file

  virtual llvm::ErrorOr<std::string> getName() {

    if (auto Status = status())

      return Status->getName().str();

    else

      return Status.getError();

  }

  /// Get the contents of the file as a \p MemoryBuffer.

  virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>

  getBuffer(const Twine &Name, int64_t FileSize = -1,

            bool RequiresNullTerminator = true, bool IsVolatile = false) = 0;

  /// Closes the file.

  virtual std::error_code close() = 0;

  // Get the same file with a different path.

  static ErrorOr<std::unique_ptr<File>>

  getWithPath(ErrorOr<std::unique_ptr<File>> Result, const Twine &P);

protected:

  // Set the file's underlying path.

  virtual void setPath(const Twine &Path) {}

};

/// A member of a directory, yielded by a directory_iterator.

/// Only information available on most platforms is included.

class directory_entry {

  std::string Path;

  llvm::sys::fs::file_type Type = llvm::sys::fs::file_type::type_unknown;

public:

  directory_entry() = default;

  directory_entry(std::string Path, llvm::sys::fs::file_type Type)

      : Path(std::move(Path)), Type(Type) {}

  llvm::StringRef path() const { return Path; }

  llvm::sys::fs::file_type type() const { return Type; }

};

namespace detail {

/// An interface for virtual file systems to provide an iterator over the

/// (non-recursive) contents of a directory.

struct DirIterImpl {

  virtual ~DirIterImpl();

  /// Sets \c CurrentEntry to the next entry in the directory on success,

  /// to directory_entry() at end,  or returns a system-defined \c error_code.

  virtual std::error_code increment() = 0;

  directory_entry CurrentEntry;

};

} // namespace detail

/// An input iterator over the entries in a virtual path, similar to

/// llvm::sys::fs::directory_iterator.

class directory_iterator {

  std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy

public:

  directory_iterator(std::shared_ptr<detail::DirIterImpl> I)

      : Impl(std::move(I)) {

    assert(Impl.get() != nullptr && "requires non-null implementation");

    if (Impl->CurrentEntry.path().empty())

      Impl.reset(); // Normalize the end iterator to Impl == nullptr.

  }

  /// Construct an 'end' iterator.

  directory_iterator() = default;

  /// Equivalent to operator++, with an error code.

  directory_iterator &increment(std::error_code &EC) {

    assert(Impl && "attempting to increment past end");

    EC = Impl->increment();

    if (Impl->CurrentEntry.path().empty())

      Impl.reset(); // Normalize the end iterator to Impl == nullptr.

    return *this;

  }

  const directory_entry &operator*() const { return Impl->CurrentEntry; }

  const directory_entry *operator->() const { return &Impl->CurrentEntry; }

  bool operator==(const directory_iterator &RHS) const {

    if (Impl && RHS.Impl)

      return Impl->CurrentEntry.path() == RHS.Impl->CurrentEntry.path();

    return !Impl && !RHS.Impl;

  }

  bool operator!=(const directory_iterator &RHS) const {

    return !(*this == RHS);

  }

};

class FileSystem;

namespace detail {

/// Keeps state for the recursive_directory_iterator.

struct RecDirIterState {

  std::stack<directory_iterator, std::vector<directory_iterator>> Stack;

  bool HasNoPushRequest = false;

};

} // end namespace detail

/// An input iterator over the recursive contents of a virtual path,

/// similar to llvm::sys::fs::recursive_directory_iterator.

class recursive_directory_iterator {

  FileSystem *FS;

  std::shared_ptr<detail::RecDirIterState>

      State; // Input iterator semantics on copy.

public:

  recursive_directory_iterator(FileSystem &FS, const Twine &Path,

                               std::error_code &EC);

  /// Construct an 'end' iterator.

  recursive_directory_iterator() = default;

  /// Equivalent to operator++, with an error code.

  recursive_directory_iterator &increment(std::error_code &EC);

  const directory_entry &operator*() const { return *State->Stack.top(); }

  const directory_entry *operator->() const { return &*State->Stack.top(); }

  bool operator==(const recursive_directory_iterator &Other) const {

    return State == Other.State; // identity

  }

  bool operator!=(const recursive_directory_iterator &RHS) const {

    return !(*this == RHS);

  }

  /// Gets the current level. Starting path is at level 0.

  int level() const {

    assert(!State->Stack.empty() &&

           "Cannot get level without any iteration state");

    return State->Stack.size() - 1;

  }

  void no_push() { State->HasNoPushRequest = true; }

};

/// The virtual file system interface.

class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {

public:

  virtual ~FileSystem();

  /// Get the status of the entry at \p Path, if one exists.

  virtual llvm::ErrorOr<Status> status(const Twine &Path) = 0;

  /// Get a \p File object for the file at \p Path, if one exists.

  virtual llvm::ErrorOr<std::unique_ptr<File>>

  openFileForRead(const Twine &Path) = 0;

  /// This is a convenience method that opens a file, gets its content and then

  /// closes the file.

  llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>

  getBufferForFile(const Twine &Name, int64_t FileSize = -1,

                   bool RequiresNullTerminator = true, bool IsVolatile = false);

  /// Get a directory_iterator for \p Dir.

  /// \note The 'end' iterator is directory_iterator().

  virtual directory_iterator dir_begin(const Twine &Dir,

                                       std::error_code &EC) = 0;

  /// Set the working directory. This will affect all following operations on

  /// this file system and may propagate down for nested file systems.

  virtual std::error_code setCurrentWorkingDirectory(const Twine &Path) = 0;

  /// Get the working directory of this file system.

  virtual llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const = 0;

  /// Gets real path of \p Path e.g. collapse all . and .. patterns, resolve

  /// symlinks. For real file system, this uses `llvm::sys::fs::real_path`.

  /// This returns errc::operation_not_permitted if not implemented by subclass.

  virtual std::error_code getRealPath(const Twine &Path,

                                      SmallVectorImpl<char> &Output) const;

  /// Check whether a file exists. Provided for convenience.

  bool exists(const Twine &Path);

  /// Is the file mounted on a local filesystem?

  virtual std::error_code isLocal(const Twine &Path, bool &Result);

  /// Make \a Path an absolute path.

  ///

  /// Makes \a Path absolute using the current directory if it is not already.

  /// An empty \a Path will result in the current directory.

  ///

  /// /absolute/path   => /absolute/path

  /// relative/../path => <current-directory>/relative/../path

  ///

  /// \param Path A path that is modified to be an absolute path.

  /// \returns success if \a path has been made absolute, otherwise a

  ///          platform-specific error_code.

  virtual std::error_code makeAbsolute(SmallVectorImpl<char> &Path) const;

  enum class PrintType { Summary, Contents, RecursiveContents };

  void print(raw_ostream &OS, PrintType Type = PrintType::Contents,

             unsigned IndentLevel = 0) const {

    printImpl(OS, Type, IndentLevel);

  }

#if !defined(NDEBUG) || defined(LLVM_ENABLE_DUMP)

  LLVM_DUMP_METHOD void dump() const;

#endif

protected:

  virtual void printImpl(raw_ostream &OS, PrintType Type,

                         unsigned IndentLevel) const {

    printIndent(OS, IndentLevel);

    OS << "FileSystem\n";

  }

  void printIndent(raw_ostream &OS, unsigned IndentLevel) const {

    for (unsigned i = 0; i < IndentLevel; ++i)

      OS << "  ";

  }

};

/// Gets an \p vfs::FileSystem for the 'real' file system, as seen by

/// the operating system.

/// The working directory is linked to the process's working directory.

/// (This is usually thread-hostile).

IntrusiveRefCntPtr<FileSystem> getRealFileSystem();

/// Create an \p vfs::FileSystem for the 'real' file system, as seen by

/// the operating system.

/// It has its own working directory, independent of (but initially equal to)

/// that of the process.

std::unique_ptr<FileSystem> createPhysicalFileSystem();

/// A file system that allows overlaying one \p AbstractFileSystem on top

/// of another.

///

/// Consists of a stack of >=1 \p FileSystem objects, which are treated as being

/// one merged file system. When there is a directory that exists in more than

/// one file system, the \p OverlayFileSystem contains a directory containing

/// the union of their contents.  The attributes (permissions, etc.) of the

/// top-most (most recently added) directory are used.  When there is a file

/// that exists in more than one file system, the file in the top-most file

/// system overrides the other(s).

class OverlayFileSystem : public FileSystem {

  using FileSystemList = SmallVector<IntrusiveRefCntPtr<FileSystem>, 1>;

  /// The stack of file systems, implemented as a list in order of

  /// their addition.

  FileSystemList FSList;

public:

  OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);

  /// Pushes a file system on top of the stack.

  void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);

  llvm::ErrorOr<Status> status(const Twine &Path) override;

  llvm::ErrorOr<std::unique_ptr<File>>

  openFileForRead(const Twine &Path) override;

  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;

  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override;

  std::error_code setCurrentWorkingDirectory(const Twine &Path) override;

  std::error_code isLocal(const Twine &Path, bool &Result) override;

  std::error_code getRealPath(const Twine &Path,

                              SmallVectorImpl<char> &Output) const override;

  using iterator = FileSystemList::reverse_iterator;

  using const_iterator = FileSystemList::const_reverse_iterator;

  using reverse_iterator = FileSystemList::iterator;

  using const_reverse_iterator = FileSystemList::const_iterator;

  using range = iterator_range<iterator>;

  using const_range = iterator_range<const_iterator>;

  /// Get an iterator pointing to the most recently added file system.

  iterator overlays_begin() { return FSList.rbegin(); }

  const_iterator overlays_begin() const { return FSList.rbegin(); }

  /// Get an iterator pointing one-past the least recently added file system.

  iterator overlays_end() { return FSList.rend(); }

  const_iterator overlays_end() const { return FSList.rend(); }

  /// Get an iterator pointing to the least recently added file system.

  reverse_iterator overlays_rbegin() { return FSList.begin(); }

  const_reverse_iterator overlays_rbegin() const { return FSList.begin(); }

  /// Get an iterator pointing one-past the most recently added file system.

  reverse_iterator overlays_rend() { return FSList.end(); }

  const_reverse_iterator overlays_rend() const { return FSList.end(); }

  range overlays_range() { return llvm::reverse(FSList); }

  const_range overlays_range() const { return llvm::reverse(FSList); }

protected:

  void printImpl(raw_ostream &OS, PrintType Type,

                 unsigned IndentLevel) const override;

};

/// By default, this delegates all calls to the underlying file system. This

/// is useful when derived file systems want to override some calls and still

/// proxy other calls.

class ProxyFileSystem : public FileSystem {

public:

  explicit ProxyFileSystem(IntrusiveRefCntPtr<FileSystem> FS)

      : FS(std::move(FS)) {}

  llvm::ErrorOr<Status> status(const Twine &Path) override {

    return FS->status(Path);

  }

  llvm::ErrorOr<std::unique_ptr<File>>

  openFileForRead(const Twine &Path) override {

    return FS->openFileForRead(Path);

  }

  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override {

    return FS->dir_begin(Dir, EC);

  }

  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {

    return FS->getCurrentWorkingDirectory();

  }

  std::error_code setCurrentWorkingDirectory(const Twine &Path) override {

    return FS->setCurrentWorkingDirectory(Path);

  }

  std::error_code getRealPath(const Twine &Path,

                              SmallVectorImpl<char> &Output) const override {

    return FS->getRealPath(Path, Output);

  }

  std::error_code isLocal(const Twine &Path, bool &Result) override {

    return FS->isLocal(Path, Result);

  }

protected:

  FileSystem &getUnderlyingFS() const { return *FS; }

private:

  IntrusiveRefCntPtr<FileSystem> FS;

  virtual void anchor();

};

namespace detail {

class InMemoryDirectory;

class InMemoryNode;

struct NewInMemoryNodeInfo {

  llvm::sys::fs::UniqueID DirUID;

  StringRef Path;

  StringRef Name;

  time_t ModificationTime;

  std::unique_ptr<llvm::MemoryBuffer> Buffer;

  uint32_t User;

  uint32_t Group;

  llvm::sys::fs::file_type Type;

  llvm::sys::fs::perms Perms;

  Status makeStatus() const;

};

class NamedNodeOrError {

  ErrorOr<std::pair<llvm::SmallString<128>, const detail::InMemoryNode *>>

      Value;

public:

  NamedNodeOrError(llvm::SmallString<128> Name,

                   const detail::InMemoryNode *Node)

      : Value(std::make_pair(Name, Node)) {}

  NamedNodeOrError(std::error_code EC) : Value(EC) {}

  NamedNodeOrError(llvm::errc EC) : Value(EC) {}

  StringRef getName() const { return (*Value).first; }

  explicit operator bool() const { return static_cast<bool>(Value); }

  operator std::error_code() const { return Value.getError(); }

  std::error_code getError() const { return Value.getError(); }

  const detail::InMemoryNode *operator*() const { return (*Value).second; }

};

} // namespace detail

/// An in-memory file system.

class InMemoryFileSystem : public FileSystem {

  std::unique_ptr<detail::InMemoryDirectory> Root;

  std::string WorkingDirectory;

  bool UseNormalizedPaths = true;

  using MakeNodeFn = llvm::function_ref<std::unique_ptr<detail::InMemoryNode>(

      detail::NewInMemoryNodeInfo)>;

  /// Create node with \p MakeNode and add it into this filesystem at \p Path.

  bool addFile(const Twine &Path, time_t ModificationTime,

               std::unique_ptr<llvm::MemoryBuffer> Buffer,

               std::optional<uint32_t> User, std::optional<uint32_t> Group,

               std::optional<llvm::sys::fs::file_type> Type,

               std::optional<llvm::sys::fs::perms> Perms, MakeNodeFn MakeNode);

  /// Looks up the in-memory node for the path \p P.

  /// If \p FollowFinalSymlink is true, the returned node is guaranteed to

  /// not be a symlink and its path may differ from \p P.

  detail::NamedNodeOrError lookupNode(const Twine &P, bool FollowFinalSymlink,

                                      size_t SymlinkDepth = 0) const;

  class DirIterator;

public:

  explicit InMemoryFileSystem(bool UseNormalizedPaths = true);

  ~InMemoryFileSystem() override;

  /// Add a file containing a buffer or a directory to the VFS with a

  /// path. The VFS owns the buffer.  If present, User, Group, Type

  /// and Perms apply to the newly-created file or directory.

  /// \return true if the file or directory was successfully added,

  /// false if the file or directory already exists in the file system with

  /// different contents.

  bool addFile(const Twine &Path, time_t ModificationTime,

               std::unique_ptr<llvm::MemoryBuffer> Buffer,

               std::optional<uint32_t> User = std::nullopt,

               std::optional<uint32_t> Group = std::nullopt,

               std::optional<llvm::sys::fs::file_type> Type = std::nullopt,

               std::optional<llvm::sys::fs::perms> Perms = std::nullopt);

  /// Add a hard link to a file.

  ///

  /// Here hard links are not intended to be fully equivalent to the classical

  /// filesystem. Both the hard link and the file share the same buffer and

  /// status (and thus have the same UniqueID). Because of this there is no way

  /// to distinguish between the link and the file after the link has been

  /// added.

  ///

  /// The \p Target path must be an existing file or a hardlink. The

  /// \p NewLink file must not have been added before. The \p Target

  /// path must not be a directory. The \p NewLink node is added as a hard

  /// link which points to the resolved file of \p Target node.

  /// \return true if the above condition is satisfied and hardlink was

  /// successfully created, false otherwise.

  bool addHardLink(const Twine &NewLink, const Twine &Target);

  /// Arbitrary max depth to search through symlinks. We can get into problems

  /// if a link links to a link that links back to the link, for example.

  static constexpr size_t MaxSymlinkDepth = 16;

  /// Add a symbolic link. Unlike a HardLink, because \p Target doesn't need

  /// to refer to a file (or refer to anything, as it happens). Also, an

  /// in-memory directory for \p Target isn't automatically created.

  bool

  addSymbolicLink(const Twine &NewLink, const Twine &Target,

                  time_t ModificationTime,

                  std::optional<uint32_t> User = std::nullopt,

                  std::optional<uint32_t> Group = std::nullopt,

                  std::optional<llvm::sys::fs::perms> Perms = std::nullopt);

  /// Add a buffer to the VFS with a path. The VFS does not own the buffer.

  /// If present, User, Group, Type and Perms apply to the newly-created file

  /// or directory.

  /// \return true if the file or directory was successfully added,

  /// false if the file or directory already exists in the file system with

  /// different contents.

  bool addFileNoOwn(const Twine &Path, time_t ModificationTime,

                    const llvm::MemoryBufferRef &Buffer,

                    std::optional<uint32_t> User = std::nullopt,

                    std::optional<uint32_t> Group = std::nullopt,

                    std::optional<llvm::sys::fs::file_type> Type = std::nullopt,

                    std::optional<llvm::sys::fs::perms> Perms = std::nullopt);

  std::string toString() const;

  /// Return true if this file system normalizes . and .. in paths.

  bool useNormalizedPaths() const { return UseNormalizedPaths; }

  llvm::ErrorOr<Status> status(const Twine &Path) override;

  llvm::ErrorOr<std::unique_ptr<File>>

  openFileForRead(const Twine &Path) override;

  directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;

  llvm::ErrorOr<std::string> getCurrentWorkingDirectory() const override {

    return WorkingDirectory;

  }

  /// Canonicalizes \p Path by combining with the current working

  /// directory and normalizing the path (e.g. remove dots). If the current

  /// working directory is not set, this returns errc::operation_not_permitted.

  ///

  /// This doesn't resolve symlinks as they are not supported in in-memory file

  /// system.

  std::error_code getRealPath(const Twine &Path,

                              SmallVectorImpl<char> &Output) const override;

  std::error_code isLocal(const Twine &Path, bool &Result) override;

  std::error_code setCurrentWorkingDirectory(const Twine &Path) override;

protected:

  void printImpl(raw_ostream &OS, PrintType Type,

                 unsigned IndentLevel) const override;

};

/// Get a globally unique ID for a virtual file or directory.

llvm::sys::fs::UniqueID getNextVirtualUniqueID();

/// Gets a \p FileSystem for a virtual file system described in YAML

/// format.

std::unique_ptr<FileSystem>

getVFSFromYAML(std::unique_ptr<llvm::MemoryBuffer> Buffer,

               llvm::SourceMgr::DiagHandlerTy DiagHandler,

               StringRef YAMLFilePath, void *DiagContext = nullptr,

               IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());

struct YAMLVFSEntry {

  template <typename T1, typename T2>

  YAMLVFSEntry(T1 &&VPath, T2 &&RPath, bool IsDirectory = false)

      : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)),

        IsDirectory(IsDirectory) {}

  std::string VPath;

  std::string RPath;

  bool IsDirectory = false;

};

class RedirectingFSDirIterImpl;

class RedirectingFileSystemParser;

/// A virtual file system parsed from a YAML file.

///

/// Currently, this class allows creating virtual files and directories. Virtual

/// files map to existing external files in \c ExternalFS, and virtual

/// directories may either map to existing directories in \c ExternalFS or list

/// their contents in the form of other virtual directories and/or files.

///

/// The basic structure of the parsed file is:

/// \verbatim

/// {

///   'version': <version number>,

///   <optional configuration>

///   'roots': [

///              <directory entries>

///            ]

/// }

/// \endverbatim

///

/// The roots may be absolute or relative. If relative they will be made

/// absolute against either current working directory or the directory where

/// the Overlay YAML file is located, depending on the 'root-relative'

/// configuration.

///

/// All configuration options are optional.

///   'case-sensitive': <boolean, default=(true for Posix, false for Windows)>

///   'use-external-names': <boolean, default=true>

///   'root-relative': <string, one of 'cwd' or 'overlay-dir', default='cwd'>

///   'overlay-relative': <boolean, default=false>

///   'fallthrough': <boolean, default=true, deprecated - use 'redirecting-with'

///                   instead>

///   'redirecting-with': <string, one of 'fallthrough', 'fallback', or

///                        'redirect-only', default='fallthrough'>

///

/// To clarify, 'root-relative' option will prepend the current working

/// directory, or the overlay directory to the 'roots->name' field only if

/// 'roots->name' is a relative path. On the other hand, when 'overlay-relative'

/// is set to 'true', external paths will always be prepended with the overlay

/// directory, even if external paths are not relative paths. The

/// 'root-relative' option has no interaction with the 'overlay-relative'

/// option.

///

/// Virtual directories that list their contents are represented as

/// \verbatim

/// {

///   'type': 'directory',

///   'name': <string>,

///   'contents': [ <file or directory entries> ]

/// }

/// \endverbatim

///

/// The default attributes for such virtual directories are:

/// \verbatim

/// MTime = now() when created

/// Perms = 0777

/// User = Group = 0

/// Size = 0

/// UniqueID = unspecified unique value

/// \endverbatim

///

/// When a path prefix matches such a directory, the next component in the path

/// is matched against the entries in the 'contents' array.

///

/// Re-mapped directories, on the other hand, are represented as

/// /// \verbatim

/// {

///   'type': 'directory-remap',

///   'name': <string>,

///   'use-external-name': <boolean>, # Optional

///   'external-contents': <path to external directory>

/// }

/// \endverbatim

///

/// and inherit their attributes from the external directory. When a path

/// prefix matches such an entry, the unmatched components are appended to the

/// 'external-contents' path, and the resulting path is looked up in the

/// external file system instead.

///

/// Re-mapped files are represented as

/// \verbatim

/// {

///   'type': 'file',

///   'name': <string>,

///   'use-external-name': <boolean>, # Optional

///   'external-contents': <path to external file>

/// }

/// \endverbatim

///

/// Their attributes and file contents are determined by looking up the file at

/// their 'external-contents' path in the external file system.

///

/// For 'file', 'directory' and 'directory-remap' entries the 'name' field may

/// contain multiple path components (e.g. /path/to/file). However, any

/// directory in such a path that contains more than one child must be uniquely

/// represented by a 'directory' entry.

///

/// When the 'use-external-name' field is set, calls to \a vfs::File::status()

/// give the external (remapped) filesystem name instead of the name the file

/// was accessed by. This is an intentional leak through the \a

/// RedirectingFileSystem abstraction layer. It enables clients to discover

/// (and use) the external file location when communicating with users or tools

/// that don't use the same VFS overlay.

///

/// FIXME: 'use-external-name' causes behaviour that's inconsistent with how

/// "real" filesystems behave. Maybe there should be a separate channel for

/// this information.

class RedirectingFileSystem : public vfs::FileSystem {

public:

  enum EntryKind { EK_Directory, EK_DirectoryRemap, EK_File };

  enum NameKind { NK_NotSet, NK_External, NK_Virtual };

  /// The type of redirection to perform.

  enum class RedirectKind {

    /// Lookup the redirected path first (ie. the one specified in

    /// 'external-contents') and if that fails "fallthrough" to a lookup of the

    /// originally provided path.

    Fallthrough,

    /// Lookup the provided path first and if that fails, "fallback" to a

    /// lookup of the redirected path.

    Fallback,

    /// Only lookup the redirected path, do not lookup the originally provided

    /// path.

    RedirectOnly

  };

  /// The type of relative path used by Roots.

  enum class RootRelativeKind {

    /// The roots are relative to the current working directory.

    CWD,

    /// The roots are relative to the directory where the Overlay YAML file

    // locates.

    OverlayDir

  };

  /// A single file or directory in the VFS.

  class Entry {

    EntryKind Kind;

    std::string Name;

  public:

    Entry(EntryKind K, StringRef Name) : Kind(K), Name(Name) {}

    virtual ~Entry() = default;

    StringRef getName() const { return Name; }

    EntryKind getKind() const { return Kind; }

  };

  /// A directory in the vfs with explicitly specified contents.