virtual_filesystem/
lib.rs

1//! # Virtual Filesystems for Rust
2//! This crate defines and implements various virtual filesystems for Rust. It's loosely inspired by the `vfs` crate with
3//! a focus on conformity with `std`.
4//!
5//! `virtual-fs` has the following FileSystems implemented out of the box:
6//! - `PhysicalFS`: A read-write physical filesystem mounted at a directory. Path traversal outside the root is permitted.
7//! - `SandboxedPhysicalFS`: A read-write physical filesystem that guards against traversal through backtracking and symbolic link
8//! traversal.
9//! - `MemoryFS`: A read-write in-memory filesystem.
10//! - `RocFS`: A "read-only collection" filesystem. This filesystem is similar to `OverlayFS`, but is read-only. This
11//! filesystem searches filesystems in mount-order for files, allowing multiple filesystems to be mounted at once.
12//! - `MountableFS`: A read-write filesystem that supports mounting other filesystems at given paths.
13//! - `ZipFS`: A read-only filesystem that mounts a ZIP archive, backed by the `zip` crate.
14//! - `TarFS` A read-only filesystem that mounts a Tarball, backed by the `tar` crate.
15
16use crate::file::{DirEntry, File, Metadata, OpenOptions};
17use mockall::automock;
18use std::io::ErrorKind;
19
20pub use error::*;
21
22/// A file system with a directory tree.
23#[automock]
24pub trait FileSystem {
25    /// Creates a directory at `path`.
26    fn create_dir(&self, path: &str) -> Result<()>;
27    /// Returns the metadata for the file/folder at `path.
28    fn metadata(&self, path: &str) -> Result<Metadata>;
29    /// Opens a file at `path` with options `options`.
30    fn open_file_options(&self, path: &str, options: &OpenOptions) -> Result<Box<dyn File>>;
31    /// Lists the files and folders contained in the directory denoted by `path`.
32    fn read_dir(&self, path: &str) -> Result<Box<dyn Iterator<Item = Result<DirEntry>>>>;
33    /// Removes the directory at `path`.
34    fn remove_dir(&self, path: &str) -> Result<()>;
35    /// Removes a file at `path`.
36    fn remove_file(&self, path: &str) -> Result<()>;
37
38    /// Creates a directory `path` and all of its parents.
39    fn create_dir_all(&self, path: &str) -> Result<()> {
40        util::create_dir_all(self, path)
41    }
42    /// Creates a file at `path` in write mode. The file will be opened in truncate mode, so all contents will be
43    /// overwritten. If this is not desirable, use `open_file` directly.
44    fn create_file(&self, path: &str) -> Result<Box<dyn File>> {
45        self.open_file_options(path, &OpenOptions::default().create(true).truncate(true))
46    }
47    /// Returns `Ok(true)` or `Ok(false)` if a file or folder at `path` does or does not exist, and `Err(_)` if the
48    /// presence cannot be verified.  
49    fn exists(&self, path: &str) -> Result<bool> {
50        match self.metadata(path) {
51            Ok(_) => Ok(true),
52            Err(err) if err.kind() == ErrorKind::NotFound => Ok(false),
53            Err(err) => Err(err),
54        }
55    }
56    /// Opens a file at `path` for reading.
57    fn open_file(&self, path: &str) -> Result<Box<dyn File>> {
58        self.open_file_options(path, &OpenOptions::default())
59    }
60}
61
62pub mod error;
63pub mod file;
64pub mod memory_fs;
65pub mod mountable_fs;
66pub mod physical_fs;
67pub mod roc_fs;
68pub mod tar_fs;
69mod tree;
70pub mod util;
71pub mod zip_fs;
virtual_filesystem/lib.rs

virtual_filesystem/
lib.rs
