Trait rsfs::GenFS
[−]
[src]
pub trait GenFS: Send + Sync { type DirBuilder: DirBuilder; type DirEntry: DirEntry; type File: File; type Metadata: Metadata; type OpenOptions: OpenOptions; type Permissions: Permissions; type ReadDir: Iterator<Item = Result<Self::DirEntry>> + Debug; fn canonicalize<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>; fn copy<P: AsRef<Path>, Q: AsRef<Path>>(
&self,
from: P,
to: Q
) -> Result<u64>; fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>; fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>; fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(
&self,
src: P,
dst: Q
) -> Result<()>; fn metadata<P: AsRef<Path>>(&self, path: P) -> Result<Self::Metadata>; fn read_dir<P: AsRef<Path>>(&self, path: P) -> Result<Self::ReadDir>; fn read_link<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>; fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>; fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>; fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>; fn rename<P: AsRef<Path>, Q: AsRef<Path>>(
&self,
from: P,
to: Q
) -> Result<()>; fn set_permissions<P: AsRef<Path>>(
&self,
path: P,
perm: Self::Permissions
) -> Result<()>; fn symlink_metadata<P: AsRef<Path>>(
&self,
path: P
) -> Result<Self::Metadata>; fn new_openopts(&self) -> Self::OpenOptions; fn new_dirbuilder(&self) -> Self::DirBuilder; fn open_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>; fn create_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>; }
The single filesystem underpinning all filesystem operations.
This trait intends to be a near drop in replacement for most uses of std::fs
. As with
std::fs
, all methods in this trait are cross-platform. Extra platform specific
functionality can be found in the extension traits of rsfs::$platform_ext
.
Examples
The normal, disk backed filesystem:
use rsfs::*; let fs = rsfs::disk::FS;
An in-memory filesystem with Unix extensions:
use rsfs::*; use rsfs::unix_ext::*; use rsfs::mem::FS; let fs = FS::with_mode(0o300);
Associated Types
type DirBuilder: DirBuilder
The DirBuilder
type in the same module implementing this trait.
type DirEntry: DirEntry
The DirEntry
type in the same module implementing this trait.
type File: File
The File
type in the same module implementing this trait.
type Metadata: Metadata
The Metadata
type in the same module implementing this trait.
type OpenOptions: OpenOptions
The OpenOptions
type in the same module implementing this trait.
type Permissions: Permissions
The Permissions
type in the same module implementing this trait.
type ReadDir: Iterator<Item = Result<Self::DirEntry>> + Debug
The ReadDir
type in the same module implementing this trait.
Required Methods
fn canonicalize<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
Returns the canonical form of a path with all intermediate components normalized and symbolic links resolved.
Errors
While there may be more error cases, this function will error in the following cases:
path
does not existA component in
path` is not a directory
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let path = fs.canonicalize("../a/../foo.txt")?;
fn copy<P: AsRef<Path>, Q: AsRef<Path>>(&self, from: P, to: Q) -> Result<u64>
Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file.
Note that this function will overwrite the contents of to
and, if from
and to
are
the same file, the file will likely be truncated by this function.
On success, the total number of bytes copied is returned.
Errors
While there may be more error cases, this function will error in the following cases:
from
is not a filefrom
does not exist- User lacks permissions to access
from
or writeto
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.copy("foo.txt", "bar.txt")?; // Copy foo.txt to bar.txt
fn create_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>
Creates a new, empty directory at the provided path.
Errors
While there may be more error cases, this function will error in the following cases:
path
exists- User lacks permissions to create a directory at
path
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.create_dir("/some/dir")?;
fn create_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>
Recursively creates a directory and all its parent components if they are missing.
Errors
While there may be more error cases, this function will error in the following cases:
- User lacks permissions to create any directories in
path
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.create_dir_all("/some/dir")?;
fn hard_link<P: AsRef<Path>, Q: AsRef<Path>>(
&self,
src: P,
dst: Q
) -> Result<()>
&self,
src: P,
dst: Q
) -> Result<()>
Creates a new hard link on the filesystem.
The dst
path will be a link pointing to the src
path.
Errors
While there may be more error cases, this function will error in the following cases:
- The
src
path is not a file or does not exist.
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.hard_link("a.txt", "b.txt")?; // Hard link a.txt to b.txt
fn metadata<P: AsRef<Path>>(&self, path: P) -> Result<Self::Metadata>
Returns metadata information of the file or directory at path.
This function will traverse symbolic links to query a directory or file.
Errors
While there may be more error cases, this function will error in the following cases:
- User lacks permissions to call
metadata
onpath
path
does not exist
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let attr = fs.metadata("/some/file/path.txt")?; // inspect attr...
fn read_dir<P: AsRef<Path>>(&self, path: P) -> Result<Self::ReadDir>
Returns an iterator over entries within a directory.
The iterator yields instances of io::Result
::
DirEntry
. New errors may be
encountered after the iterator is initially constructed.
Errors
While there may be more error cases, this function will error in the following cases:
path
does not existpath
is not a directory- User lacks permissions to read the directory at
path
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); for entry in fs.read_dir("/")? { println!("{:?}", entry?.path()); }
fn read_link<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
Reads a symbolic link, returning the entry the link points to.
Errors
While there may be more error cases, this function will error in the following cases:
path
does not existpath
is not a symbolic link
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let path = fs.read_link("foo")?;
fn remove_dir<P: AsRef<Path>>(&self, path: P) -> Result<()>
Removes an existing, empty directory.
Errors
While there may be more error cases, this function will error in the following cases:
path
is not a directory- User lacks permissions to remove the directory at
path
- The directory is not empty
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.remove_dir("/some/dir")?;
fn remove_dir_all<P: AsRef<Path>>(&self, path: P) -> Result<()>
Removes a directory at path after removing all of its contents.
Errors
See remove_dir
and remove_file
.
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.remove_dir_all("/some/dir")?;
fn remove_file<P: AsRef<Path>>(&self, path: P) -> Result<()>
Removes a file from the filesystem.
Errors
While there may be more error cases, this function will error in the following cases:
path
is a directory- User lacks permissions to remove the file at
path
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.remove_file("a.txt")?;
fn rename<P: AsRef<Path>, Q: AsRef<Path>>(&self, from: P, to: Q) -> Result<()>
Renames a file or directory at from
to to
, replacing to
if it exists.
Platform-specific behavior
Behavior differs between Unix and Windows. On Unix, if from
is a directory, to
must
also be an (empty) directory. If from
is not a directory, to
must not be a directory.
On Windows, from
can be anything, but to
must not be a directory.
Errors
While there may be more error cases, this function will error in the following cases:
from
does not exist- User lacks permissions to rename
from
from
andto
are on separate filesystems
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); fs.rename("a.txt", "b.txt")?;
fn set_permissions<P: AsRef<Path>>(
&self,
path: P,
perm: Self::Permissions
) -> Result<()>
&self,
path: P,
perm: Self::Permissions
) -> Result<()>
Changes the permissions of a file or directory.
Errors
While there may be more error cases, this function will error in the following cases:
path
does not exist- User lacks permissions to changes the attributes of the entry at
path
Examples
use rsfs::*; use rsfs::unix_ext::*; use rsfs::mem::{FS, Permissions}; let fs = FS::new(); fs.set_permissions("foo.pem", Permissions::from_mode(0o400))?;
fn symlink_metadata<P: AsRef<Path>>(&self, path: P) -> Result<Self::Metadata>
Query the metadata about a file without following symlinks.
Errors
While there may be more error cases, this function will error in the following cases:
- User lacks permissions to call
symlink_metadata
onpath
path
does not exist
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let attr = fs.symlink_metadata("/some/file/path.txt")?; // inspect attr...
fn new_openopts(&self) -> Self::OpenOptions
Returns a new OpenOptions for a file for this filesytem.
This method replaces std::fs::OpenOptions::new()
, which now needs to be a part of this
trait to ensure any new file belongs to the GenFS
that created the OpenOptions
.
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let mut options = fs.new_openopts(); let file = options.read(true).open("foo.txt")?;
fn new_dirbuilder(&self) -> Self::DirBuilder
Returns a new DirBuilder for a directory for this filesystem.
This method replaces std::fs::DirBuilder::new()
, which now needs to be a part of this
trait to ensure any new directory belongs to the GenFS
that created the DirBuilder
.
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let mut builder = fs.new_dirbuilder();
fn open_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>
Opens a file in read-only mode.
This method replaces std::fs::File::open()
, which now needs to be a part of this trait
to ensure that the opened file belongs to the calling GenFS
.
See OpenOptions::open
for more details.
Errors
This function will return an error if path
does not exist. Other errors may be returned
according to OpenOptions::open
.
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let mut file = fs.open_file("foo.txt")?;
fn create_file<P: AsRef<Path>>(&self, path: P) -> Result<Self::File>
Opens a file in write-only mode.
This method replaces std::fs::File::create()
, which now needs to be a part of this trait
to ensure that the created file belongs to the calling GenFS
.
This function will create a file if it does not exist and truncate it if it does.
See OpenOptions::create
for more details.
Examples
use rsfs::*; use rsfs::mem::FS; let fs = FS::new(); let mut file = fs.create_file("foo.txt")?;