WIP: docs(fs): add some documentation
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful

This commit is contained in:
Paul Campbell 2024-04-29 07:25:31 +01:00 committed by Paul Campbell
parent 9943a0fe4e
commit 805d0b3bb6
2 changed files with 95 additions and 1 deletions

View file

@ -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>;
}

View file

@ -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)
}