From 1394563083c42b86c5e2412ee238bbd8b2348310 Mon Sep 17 00:00:00 2001 From: Paul Campbell Date: Mon, 29 Apr 2024 07:25:31 +0100 Subject: [PATCH] WIP: docs(fs): add some documentation --- src/fs/like.rs | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++ src/fs/mod.rs | 20 ++++++++++++- 2 files changed, 95 insertions(+), 1 deletion(-) diff --git a/src/fs/like.rs b/src/fs/like.rs index 19ae0d9..c01b4ea 100644 --- a/src/fs/like.rs +++ b/src/fs/like.rs @@ -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>>>; + /// 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; + + /// 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; + + /// 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; + + /// 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; + + /// 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; } diff --git a/src/fs/mod.rs b/src/fs/mod.rs index e2b369b..b86b188 100644 --- a/src/fs/mod.rs +++ b/src/fs/mod.rs @@ -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 = core::result::Result; +/// 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 { temp::new().map(FileSystem::Temp) }