ari-party/rojo
1
0
Fork 0
forked from rojo-rbx/rojo
Code Pull Requests Activity

vfs: Expand documentation

Browse Source
This commit is contained in:
Lucien Greathouse
2020-02-21 23:34:56 -08:00
parent 1b24cd36e0
commit fefc7a69cd
2 changed files with 135 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
vfs/src/lib.rs
View File

@@ -5,7 +5,7 @@ mod std_backend;
use std::io;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
use std::sync::{Arc, Mutex, MutexGuard};
pub use memory_backend::MemoryBackend;
pub use noop_backend::NoopBackend;
@@ -15,6 +15,7 @@ pub use std_backend::StdBackend;
mod sealed {
use super::*;
/// Sealing trait for VfsBackend.
pub trait Sealed {}
impl Sealed for MemoryBackend {}
@@ -22,6 +23,9 @@ mod sealed {
impl Sealed for StdBackend {}
}
/// Trait that transforms `io::Result<T>` into `io::Result<Option<T>>`.
///
/// `Ok(None)` takes the place of IO errors whose `io::ErrorKind` is `NotFound`.
pub trait IoResultExt<T> {
fn with_not_found(self) -> io::Result<Option<T>>;
}
@@ -57,6 +61,9 @@ pub trait VfsBackend: sealed::Sealed + Send + 'static {
fn unwatch(&mut self, path: &Path) -> io::Result<()>;
}
/// Vfs equivalent to [`std::fs::DirEntry`][std::fs::DirEntry].
///
/// [std::fs::DirEntry]: https://doc.rust-lang.org/stable/std/fs/struct.DirEntry.html
pub struct DirEntry {
path: PathBuf,
}
@@ -67,6 +74,9 @@ impl DirEntry {
}
}
/// Vfs equivalent to [`std::fs::ReadDir`][std::fs::ReadDir].
///
/// [std::fs::ReadDir]: https://doc.rust-lang.org/stable/std/fs/struct.ReadDir.html
pub struct ReadDir {
inner: Box<dyn Iterator<Item = io::Result<DirEntry>>>,
}
@@ -79,6 +89,9 @@ impl Iterator for ReadDir {
}
}
/// Vfs equivalent to [`std::fs::Metadata`][std::fs::Metadata].
///
/// [std::fs::Metadata]: https://doc.rust-lang.org/stable/std/fs/struct.Metadata.html
#[derive(Debug)]
pub struct Metadata {
is_file: bool,
@@ -102,57 +115,55 @@ pub enum VfsEvent {
Remove(PathBuf),
}
struct VfsLock {
/// Contains implementation details of the Vfs, wrapped by `Vfs` and `VfsLock`,
/// the public interfaces to this type.
struct VfsInner {
backend: Box<dyn VfsBackend>,
}
impl VfsLock {
pub fn read<P: AsRef<Path>>(&mut self, path: P) -> io::Result<Arc<Vec<u8>>> {
impl VfsInner {
fn read<P: AsRef<Path>>(&mut self, path: P) -> io::Result<Arc<Vec<u8>>> {
let path = path.as_ref();
let contents = self.backend.read(path)?;
self.backend.watch(path)?;
Ok(Arc::new(contents))
}
pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(
&mut self,
path: P,
contents: C,
) -> io::Result<()> {
fn write<P: AsRef<Path>, C: AsRef<[u8]>>(&mut self, path: P, contents: C) -> io::Result<()> {
let path = path.as_ref();
let contents = contents.as_ref();
self.backend.write(path, contents)
}
pub fn read_dir<P: AsRef<Path>>(&mut self, path: P) -> io::Result<ReadDir> {
fn read_dir<P: AsRef<Path>>(&mut self, path: P) -> io::Result<ReadDir> {
let path = path.as_ref();
let dir = self.backend.read_dir(path)?;
self.backend.watch(path)?;
Ok(dir)
}
pub fn remove_file<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
fn remove_file<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
let path = path.as_ref();
let _ = self.backend.unwatch(path);
self.backend.remove_file(path)
}
pub fn remove_dir_all<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
fn remove_dir_all<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
let path = path.as_ref();
let _ = self.backend.unwatch(path);
self.backend.remove_dir_all(path)
}
pub fn metadata<P: AsRef<Path>>(&mut self, path: P) -> io::Result<Metadata> {
fn metadata<P: AsRef<Path>>(&mut self, path: P) -> io::Result<Metadata> {
let path = path.as_ref();
self.backend.metadata(path)
}
pub fn event_receiver(&self) -> crossbeam_channel::Receiver<VfsEvent> {
fn event_receiver(&self) -> crossbeam_channel::Receiver<VfsEvent> {
self.backend.event_receiver()
}
pub fn commit_event(&mut self, event: &VfsEvent) -> io::Result<()> {
fn commit_event(&mut self, event: &VfsEvent) -> io::Result<()> {
match event {
VfsEvent::Remove(path) => {
let _ = self.backend.unwatch(&path);
@@ -166,7 +177,7 @@ impl VfsLock {
/// A virtual filesystem with a configurable backend.
pub struct Vfs {
inner: Mutex<VfsLock>,
inner: Mutex<VfsInner>,
}
impl Vfs {
@@ -177,7 +188,7 @@ impl Vfs {
/// Creates a new `Vfs` with the given backend.
pub fn new<B: VfsBackend>(backend: B) -> Self {
let lock = VfsLock {
let lock = VfsInner {
backend: Box::new(backend),
};
@@ -186,12 +197,19 @@ impl Vfs {
}
}
pub fn lock(&self) -> VfsLock<'_> {
VfsLock {
inner: self.inner.lock().unwrap(),
}
}
/// Read a file from the VFS, or the underlying backend if it isn't
/// resident.
///
/// Roughly equivalent to [`std::fs::read`][std::fs::read].
///
/// [std::fs::read]: https://doc.rust-lang.org/stable/std/fs/fn.read.html
#[inline]
pub fn read<P: AsRef<Path>>(&self, path: P) -> io::Result<Arc<Vec<u8>>> {
let path = path.as_ref();
self.inner.lock().unwrap().read(path)
@@ -202,6 +220,7 @@ impl Vfs {
/// Roughly equivalent to [`std::fs::write`][std::fs::write].
///
/// [std::fs::write]: https://doc.rust-lang.org/stable/std/fs/fn.write.html
#[inline]
pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(&self, path: P, contents: C) -> io::Result<()> {
let path = path.as_ref();
let contents = contents.as_ref();
@@ -213,6 +232,7 @@ impl Vfs {
/// Roughly equivalent to [`std::fs::read_dir`][std::fs::read_dir].
///
/// [std::fs::read_dir]: https://doc.rust-lang.org/stable/std/fs/fn.read_dir.html
#[inline]
pub fn read_dir<P: AsRef<Path>>(&self, path: P) -> io::Result<ReadDir> {
let path = path.as_ref();
self.inner.lock().unwrap().read_dir(path)
@@ -223,6 +243,7 @@ impl Vfs {
/// Roughly equivalent to [`std::fs::remove_file`][std::fs::remove_file].
///
/// [std::fs::remove_file]: https://doc.rust-lang.org/stable/std/fs/fn.remove_file.html
#[inline]
pub fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
let path = path.as_ref();
self.inner.lock().unwrap().remove_file(path)
@@ -233,6 +254,7 @@ impl Vfs {
/// Roughly equivalent to [`std::fs::remove_dir_all`][std::fs::remove_dir_all].
///
/// [std::fs::remove_dir_all]: https://doc.rust-lang.org/stable/std/fs/fn.remove_dir_all.html
#[inline]
pub fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
let path = path.as_ref();
self.inner.lock().unwrap().remove_dir_all(path)
@@ -243,18 +265,112 @@ impl Vfs {
/// Roughly equivalent to [`std::fs::metadata`][std::fs::metadata].
///
/// [std::fs::metadata]: https://doc.rust-lang.org/stable/std/fs/fn.metadata.html
#[inline]
pub fn metadata<P: AsRef<Path>>(&self, path: P) -> io::Result<Metadata> {
let path = path.as_ref();
self.inner.lock().unwrap().metadata(path)
}
/// Retrieve a handle to the event receiver for this `Vfs`.
#[inline]
pub fn event_receiver(&self) -> crossbeam_channel::Receiver<VfsEvent> {
self.inner.lock().unwrap().event_receiver()
}
/// Commit an event to this `Vfs`.
#[inline]
pub fn commit_event(&self, event: &VfsEvent) -> io::Result<()> {
self.inner.lock().unwrap().commit_event(event)
}
}
/// A locked handle to a `Vfs`, created by `Vfs::lock`.
pub struct VfsLock<'a> {
inner: MutexGuard<'a, VfsInner>,
}
impl VfsLock<'_> {
/// Read a file from the VFS, or the underlying backend if it isn't
/// resident.
///
/// Roughly equivalent to [`std::fs::read`][std::fs::read].
///
/// [std::fs::read]: https://doc.rust-lang.org/stable/std/fs/fn.read.html
#[inline]
pub fn read<P: AsRef<Path>>(&mut self, path: P) -> io::Result<Arc<Vec<u8>>> {
let path = path.as_ref();
self.inner.read(path)
}
/// Write a file to the VFS and the underlying backend.
///
/// Roughly equivalent to [`std::fs::write`][std::fs::write].
///
/// [std::fs::write]: https://doc.rust-lang.org/stable/std/fs/fn.write.html
#[inline]
pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(
&mut self,
path: P,
contents: C,
) -> io::Result<()> {
let path = path.as_ref();
let contents = contents.as_ref();
self.inner.write(path, contents)
}
/// Read all of the children of a directory.
///
/// Roughly equivalent to [`std::fs::read_dir`][std::fs::read_dir].
///
/// [std::fs::read_dir]: https://doc.rust-lang.org/stable/std/fs/fn.read_dir.html
#[inline]
pub fn read_dir<P: AsRef<Path>>(&mut self, path: P) -> io::Result<ReadDir> {
let path = path.as_ref();
self.inner.read_dir(path)
}
/// Remove a file.
///
/// Roughly equivalent to [`std::fs::remove_file`][std::fs::remove_file].
///
/// [std::fs::remove_file]: https://doc.rust-lang.org/stable/std/fs/fn.remove_file.html
#[inline]
pub fn remove_file<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
let path = path.as_ref();
self.inner.remove_file(path)
}
/// Remove a directory and all of its descendants.
///
/// Roughly equivalent to [`std::fs::remove_dir_all`][std::fs::remove_dir_all].
///
/// [std::fs::remove_dir_all]: https://doc.rust-lang.org/stable/std/fs/fn.remove_dir_all.html
#[inline]
pub fn remove_dir_all<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
let path = path.as_ref();
self.inner.remove_dir_all(path)
}
/// Query metadata about the given path.
///
/// Roughly equivalent to [`std::fs::metadata`][std::fs::metadata].
///
/// [std::fs::metadata]: https://doc.rust-lang.org/stable/std/fs/fn.metadata.html
#[inline]
pub fn metadata<P: AsRef<Path>>(&mut self, path: P) -> io::Result<Metadata> {
let path = path.as_ref();
self.inner.metadata(path)
}
/// Retrieve a handle to the event receiver for this `Vfs`.
#[inline]
pub fn event_receiver(&self) -> crossbeam_channel::Receiver<VfsEvent> {
self.inner.event_receiver()
}
/// Commit an event to this `Vfs`.
#[inline]
pub fn commit_event(&mut self, event: &VfsEvent) -> io::Result<()> {
self.inner.commit_event(event)
}
}

4
vfs/src/memory_backend.rs
View File

@@ -4,9 +4,9 @@ use std::path::{Path, PathBuf};
use crate::{Metadata, ReadDir, VfsBackend, VfsEvent, VfsSnapshot};
/// `VfsBackend` that reads from an in-memory filesystem.
/// `VfsBackend` that reads from an in-memory filesystem, intended for setting
/// up testing scenarios quickly.
#[derive(Debug)]
#[non_exhaustive]
pub struct MemoryBackend {
entries: HashMap<PathBuf, Entry>,
orphans: BTreeSet<PathBuf>,