WIP: docs(fs): add some documentation
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
This commit is contained in:
parent
d90a1c42c8
commit
a27d39753b
2 changed files with 95 additions and 1 deletions
|
@ -4,20 +4,96 @@ use super::Result;
|
|||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
/// A handle for accessing the filesystem.
|
||||
pub trait FileSystemLike {
|
||||
/// Returns the base directory for the filesystem that this handle can access.
|
||||
///
|
||||
/// Many methods expect a [Path] paremeter. This [Path] must be within the base directory of the
|
||||
/// handle. Call [FileSystemLike::base] to get this.
|
||||
///
|
||||
/// To construct a [Path] within the filesystem:
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::new(std::env::current_dir()?);
|
||||
/// let file_name = fs.base().join("foo");
|
||||
/// ```
|
||||
fn base(&self) -> &Path;
|
||||
|
||||
/// Creates a directory at the path. The parent directory must already exists, if it doesn't
|
||||
/// consider using [FileSystemLike::dir_create_all] instead.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::temp()?;
|
||||
/// let dir_name = fs.base().join("subdir");
|
||||
/// fs.dir_create(&dir_name)?;
|
||||
/// ```
|
||||
fn dir_create(&self, path: &Path) -> Result<()>;
|
||||
|
||||
/// Creates a directory and any missing parents as the path.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::temp()?;
|
||||
/// let path_name = fs.base().join("subdir").join("child");
|
||||
/// fs.dir_create_all(&path_name)?;
|
||||
/// ```
|
||||
fn dir_create_all(&self, path: &Path) -> Result<()>;
|
||||
|
||||
/// Reads the items in a directory and returns them as an iterator.
|
||||
fn dir_read(&self, path: &Path) -> Result<Box<dyn Iterator<Item = Result<DirItem>>>>;
|
||||
|
||||
/// Reads a file into a [String]. Will attempt to read the whole file into memory in one go.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::new(std::env::current_dir()?);
|
||||
/// let file_name = fs.base().join("existing_file.txt");
|
||||
/// let file_contents = fs.file_read_to_string(&file_name)?;
|
||||
/// ```
|
||||
fn file_read_to_string(&self, path: &Path) -> Result<String>;
|
||||
|
||||
/// Writes a string slice to a file.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::temp()?;
|
||||
/// let file_name = fs.base().join("new_file");
|
||||
/// let contents = "contents of new file";
|
||||
/// fs.file_write(&file_name, contents)?;
|
||||
/// ```
|
||||
fn file_write(&self, path: &Path, contents: &str) -> Result<()>;
|
||||
|
||||
/// Checks that the path exists.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::new(std::env::current_dir()?);
|
||||
/// let path = fs.base().join("foo");
|
||||
/// let exists: bool = fs.path_exists(&path)?;
|
||||
/// ```
|
||||
fn path_exists(&self, path: &Path) -> Result<bool>;
|
||||
|
||||
/// Checks whether the path is a directory.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::new(std::env::current_dir()?);
|
||||
/// let path = fs.base().join("foo");
|
||||
/// let is_dir: bool = fs.path_is_dir(&path)?;
|
||||
/// ```
|
||||
fn path_is_dir(&self, path: &Path) -> Result<bool>;
|
||||
|
||||
/// Checks whether the path is a file.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::new(std::env::current_dir()?);
|
||||
/// let path = fs.base().join("foo");
|
||||
/// let is_file: bool = fs.path_is_file(&path)?;
|
||||
/// ```
|
||||
fn path_is_file(&self, path: &Path) -> Result<bool>;
|
||||
|
||||
/// Creates a new [PathBuf] within the filesystem.
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::temp()?;
|
||||
/// let path_of = fs.path_of("subdir/file.txt")?;
|
||||
/// let path = fs.base().join("subdir").join("file.txt");
|
||||
/// assert_eq!(path_of, path);
|
||||
/// ```
|
||||
fn path_of(&self, path: PathBuf) -> Result<PathBuf>;
|
||||
}
|
||||
|
|
|
@ -4,7 +4,7 @@ use derive_more::From;
|
|||
|
||||
use crate::fs::like::FileSystemLike;
|
||||
|
||||
mod like;
|
||||
pub mod like;
|
||||
mod real;
|
||||
mod temp;
|
||||
|
||||
|
@ -31,10 +31,28 @@ impl std::error::Error for Error {}
|
|||
|
||||
pub type Result<T> = core::result::Result<T, Error>;
|
||||
|
||||
/// Creates a new handle for accessing the filesystem.
|
||||
///
|
||||
/// The base parameter is the root directory that all operations must be within.
|
||||
pub const fn new(base: PathBuf) -> FileSystem {
|
||||
FileSystem::Real(real::new(base))
|
||||
}
|
||||
|
||||
/// Creates a new handle for accessing a temporary directory on the filesystem.
|
||||
///
|
||||
/// When this handle is dropped, the temporary directory is deleted.
|
||||
///
|
||||
/// Calling base on the handle will return the temporary directory.
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
/// This will create a temporary directory and create a file inside it called 'foo':
|
||||
///
|
||||
/// ```no_run
|
||||
/// let fs = kxio::fs::temp()?;
|
||||
/// let file_name = fs.base().join("foo");
|
||||
/// fs.file_write(&file_name, "contents")?;
|
||||
/// ```
|
||||
pub fn temp() -> Result<FileSystem> {
|
||||
temp::new().map(FileSystem::Temp)
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue