feat: remove need for mutability

adds rustdocs

justfile

@@ -1,8 +1,10 @@
 build:
+  cargo fmt
   cargo fmt --check
   cargo hack --feature-powerset clippy
   cargo hack --feature-powerset build
   cargo hack --feature-powerset test
+  cargo doc
 
 install-hooks:
   @echo "Installing git hooks"

src/fs/dir.rs

@@ -1,22 +1,90 @@
 //
 use crate::fs::{DirItem, DirItemIterator, Result};
 
-use super::path::{DirG, PathReal};
+use super::{
+    path::{DirG, PathReal},
+    FileG, PathG,
+};
 
 impl<'base, 'path> PathReal<'base, 'path, DirG> {
-    pub fn create(&mut self) -> Result<()> {
+    /// Creates a new, empty directory at the path
+    ///
+    /// Wrapper for [std::fs::create_dir]
+    ///
+    /// ```
+    /// # fn try_main() -> kxio::fs::Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// let dir = fs.dir(&path);
+    /// dir.create()?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn create(&self) -> Result<()> {
         self.check_error()?;
         std::fs::create_dir(self.as_pathbuf()).map_err(Into::into)
     }
 
-    pub fn create_all(&mut self) -> Result<()> {
+    /// Recursively create a directory and all of its parent components if they are missing.
+    ///
+    /// Wrapper for [std::fs::create_dir_all]
+    ///
+    /// ```
+    /// # fn try_main() -> kxio::fs::Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo").join("bar");
+    /// let dir = fs.dir(&path);
+    /// dir.create_all()?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn create_all(&self) -> Result<()> {
         self.check_error()?;
         std::fs::create_dir_all(self.as_pathbuf()).map_err(Into::into)
     }
 
-    pub fn read(&mut self) -> Result<Box<dyn Iterator<Item = Result<DirItem>>>> {
+    /// Returns an iterator over the entries within a directory.
+    ///
+    /// Wrapper for [std::fs::read_dir]
+    ///
+    /// ```
+    /// # fn try_main() -> kxio::fs::Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo").join("bar");
+    /// let dir = fs.dir(&path);
+    /// for entry in dir.read()? { /* ... */ }
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn read(&self) -> Result<Box<dyn Iterator<Item = Result<DirItem>>>> {
         self.check_error()?;
         let read_dir = std::fs::read_dir(self.as_pathbuf())?;
         Ok(Box::new(DirItemIterator::new(read_dir)))
     }
 }
+impl<'base, 'path> TryFrom<PathReal<'base, 'path, PathG>> for PathReal<'base, 'path, FileG> {
+    type Error = crate::fs::Error;
+
+    fn try_from(path: PathReal<'base, 'path, PathG>) -> std::result::Result<Self, Self::Error> {
+        match path.as_file() {
+            Ok(Some(dir)) => Ok(dir.clone()),
+            Ok(None) => Err(crate::fs::Error::NotADirectory {
+                path: path.as_pathbuf(),
+            }),
+            Err(err) => Err(err),
+        }
+    }
+}
+impl<'base, 'path> TryFrom<PathReal<'base, 'path, PathG>> for PathReal<'base, 'path, DirG> {
+    type Error = crate::fs::Error;
+
+    fn try_from(path: PathReal<'base, 'path, PathG>) -> std::result::Result<Self, Self::Error> {
+        match path.as_dir() {
+            Ok(Some(dir)) => Ok(dir.clone()),
+            Ok(None) => Err(crate::fs::Error::NotADirectory {
+                path: path.as_pathbuf(),
+            }),
+            Err(err) => Err(err),
+        }
+    }
+}

src/fs/file.rs

@@ -3,16 +3,40 @@ use crate::fs::Result;
 
 use super::{
     path::{FileG, PathReal},
-    reader::ReaderReal,
+    reader::Reader,
 };
 
 impl<'base, 'path> PathReal<'base, 'path, FileG> {
-    pub fn reader(&mut self) -> Result<ReaderReal> {
+    /// Returns a [Reader] for the file.
+    ///
+    /// ```
+    /// # fn try_main() -> kxio::fs::Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo").join("bar");
+    /// let file = fs.file(&path);
+    /// let reader = file.reader()?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn reader(&self) -> Result<Reader> {
         self.check_error()?;
-        ReaderReal::new(&self.as_pathbuf())
+        Reader::new(&self.as_pathbuf())
     }
 
-    pub fn write(&mut self, contents: &str) -> Result<()> {
+    /// Writes a slice as the entire contents of a file.
+    ///
+    /// Wrapper for [std::fs::write]
+    ///
+    /// ```
+    /// # fn try_main() -> kxio::fs::Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo").join("bar");
+    /// let file = fs.file(&path);
+    /// file.write("new file contents")?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn write<C: AsRef<[u8]>>(&self, contents: C) -> Result<()> {
         self.check_error()?;
         std::fs::write(self.as_pathbuf(), contents).map_err(Into::into)
     }

src/fs/mod.rs

@@ -17,6 +17,8 @@ mod system;
 mod temp;
 
 pub use dir_item::{DirItem, DirItemIterator};
+pub use path::*;
+pub use reader::Reader;
 pub use result::{Error, Result};
 pub use system::FileSystem;
 

src/fs/path.rs

@@ -8,16 +8,22 @@ use crate::fs::{Error, Result};
 
 pub trait PathType {}
 
+#[derive(Clone, Debug)]
 pub struct PathG;
 impl PathType for PathG {}
 
+#[derive(Clone, Debug)]
 pub struct FileG;
 impl PathType for FileG {}
 
+#[derive(Clone, Debug)]
 pub struct DirG;
 impl PathType for DirG {}
 
-#[derive(Debug)]
+/// Represents a path in the filesystem.
+///
+/// It can be a simple path, or it can be a file or a directory.
+#[derive(Clone, Debug)]
 pub struct PathReal<'base, 'path, T: PathType> {
     base: &'base Path,
     path: &'path Path,
@@ -34,6 +40,18 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
         }
     }
 
+    /// Returns a [PathBuf] for the path.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// let path = fs.path(&path);
+    /// let pathbuf = path.as_pathbuf();
+    /// #    Ok(())
+    /// # }
+    /// ```
     pub fn as_pathbuf(&self) -> PathBuf {
         self.base.join(self.path)
     }
@@ -71,29 +89,84 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
         Ok(abs_path)
     }
 
-    pub(super) fn check_error(&mut self) -> Result<()> {
+    pub(super) fn check_error(&self) -> Result<()> {
-        if let Some(error) = self.error.take() {
+        if let Some(error) = &self.error {
-            return Err(error);
+            Err(error.clone())
+        } else {
+            Ok(())
         }
-        Ok(())
     }
 
-    pub fn exists(&mut self) -> Result<bool> {
+    /// Returns true if the path exists.
+    ///
+    /// N.B. If you have the path used to create the file or directory, you
+    /// should use [std::path::Path::exists] instead.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// let dir = fs.dir(&path);
+    /// #    dir.create()?;
+    /// if dir.exists()? { /* ... */ }
+    /// #    Ok(())
+    /// # }
+    /// ```
+    pub fn exists(&self) -> Result<bool> {
         self.check_error()?;
         Ok(self.as_pathbuf().exists())
     }
 
-    pub fn is_dir(&mut self) -> Result<bool> {
+    /// Returns true if the path is a directory.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// #    fs.dir(&path).create()?;
+    /// if path.is_dir() { /* ... */ }
+    /// #    Ok(())
+    /// # }
+    /// ```
+    pub fn is_dir(&self) -> Result<bool> {
         self.check_error()?;
         Ok(self.as_pathbuf().is_dir())
     }
 
-    pub fn is_file(&mut self) -> Result<bool> {
+    /// Returns true if the path is a file.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// #    fs.dir(&path).create()?;
+    /// if path.is_file() { /* ... */ }
+    /// #    Ok(())
+    /// # }
+    /// ```
+    pub fn is_file(&self) -> Result<bool> {
         self.check_error()?;
         Ok(self.as_pathbuf().is_file())
     }
 
-    pub fn as_dir(&mut self) -> Result<Option<PathReal<'base, 'path, DirG>>> {
+    /// Returns the path as a directory if it exists and is a directory, otherwise
+    /// it will return None.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// #    fs.dir(&path).create()?;
+    /// let file = fs.path(&path);
+    /// if let Ok(Some(dir)) = file.as_dir() { /* ... */ }
+    /// #    Ok(())
+    /// # }
+    /// ```
+    pub fn as_dir(&self) -> Result<Option<PathReal<'base, 'path, DirG>>> {
         self.check_error()?;
         if self.as_pathbuf().is_dir() {
             Ok(Some(PathReal::new(self.base, self.path)))
@@ -102,7 +175,21 @@ impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
         }
     }
 
-    pub fn as_file(&mut self) -> Result<Option<PathReal<'base, 'path, FileG>>> {
+    /// Returns the path as a file if it exists and is a file, otherwise
+    /// it will return None.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// #    fs.dir(&path).create()?;
+    /// let file = fs.path(&path);
+    /// if let Ok(Some(file)) = file.as_file() { /* ... */ }
+    /// #    Ok(())
+    /// # }
+    /// ```
+    pub fn as_file(&self) -> Result<Option<PathReal<'base, 'path, FileG>>> {
         self.check_error()?;
         if self.as_pathbuf().is_file() {
             Ok(Some(PathReal::new(self.base, self.path)))

src/fs/reader.rs

@@ -3,24 +3,68 @@ use std::{fmt::Display, path::Path, str::Lines};
 
 use crate::fs::Result;
 
-pub struct ReaderReal {
+/// A reader for a file.
+pub struct Reader {
     contents: String,
 }
-impl ReaderReal {
+impl Reader {
     pub(super) fn new(path: &Path) -> Result<Self> {
         let contents = std::fs::read_to_string(path)?;
         Ok(Self { contents })
     }
 
+    /// Returns the contents of the file as a string.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// let file = fs.file(&path);
+    /// # file.write("new file contents")?;
+    /// let contents = file.reader()?.contents();
+    /// #    Ok(())
+    /// # }
+    /// ```
+    pub fn contents(&self) -> &str {
+        &self.contents
+    }
+
+    /// Returns the contents of the file as a string.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// let file = fs.file(&path);
+    /// # file.write("new file contents")?;
+    /// let contents = file.reader()?.as_str();
+    /// #    Ok(())
+    /// # }
+    /// ```
     pub fn as_str(&self) -> &str {
         &self.contents
     }
 
+    /// Returns an iterator over the lines in the file.
+    ///
+    /// ```
+    /// # use kxio::fs::Result;
+    /// # fn main() -> Result<()> {
+    /// let fs = kxio::fs::temp()?;
+    /// let path = fs.base().join("foo");
+    /// let file = fs.file(&path);
+    /// # file.write("new file contents")?;
+    /// let lines = file.reader()?.lines();
+    /// #    Ok(())
+    /// # }
+    /// ```
     pub fn lines(&self) -> Lines<'_> {
         self.contents.lines()
     }
 }
-impl Display for ReaderReal {
+impl Display for Reader {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}", self.contents)
     }

src/fs/result.rs

@@ -12,6 +12,8 @@ use derive_more::From;
 pub enum Error {
     Io(std::io::Error),
 
+    IoString(String),
+
     #[display("Path access attempted outside of base ({base:?}): {path:?}")]
     PathTraversal {
         base: PathBuf,
@@ -24,6 +26,19 @@ pub enum Error {
     },
 }
 impl std::error::Error for Error {}
+impl Clone for Error {
+    fn clone(&self) -> Self {
+        match self {
+            Error::Io(err) => Error::IoString(err.to_string()),
+            Error::IoString(err) => Error::IoString(err.clone()),
+            Error::PathTraversal { base, path } => Error::PathTraversal {
+                base: base.clone(),
+                path: path.clone(),
+            },
+            Error::NotADirectory { path } => Error::NotADirectory { path: path.clone() },
+        }
+    }
+}
 
 /// Represents a success or a failure.
 ///

src/fs/system.rs

@@ -14,6 +14,7 @@ impl FileSystem {
     pub const fn new(base: PathBuf) -> Self {
         Self { base }
     }
+
     pub fn base(&self) -> &Path {
         &self.base
     }
@@ -24,6 +25,7 @@ impl FileSystem {
         Ok(path_of)
     }
 
+    /// Access the path as a directory.
     pub fn dir<'base, 'path>(&'base self, path: &'path Path) -> PathReal<'base, 'path, DirG> {
         let mut dir = PathReal::new(self.base(), path);
 

tests/fs.rs

@@ -40,7 +40,7 @@ mod path {
         let fs = fs::temp().expect("temp fs");
 
         let path = fs.base().join("foo");
-        let mut dir = fs.dir(&path);
+        let dir = fs.dir(&path);
         dir.create().expect("create");
 
         let_assert!(Ok(Some(as_dir)) = fs.path(&path).as_dir());
@@ -55,10 +55,10 @@ mod path {
         let fs = fs::temp().expect("temp fs");
 
         let path = fs.base().join("foo");
-        let mut file = fs.file(&path);
+        let file = fs.file(&path);
         file.write("contents").expect("create");
 
-        let_assert!(Ok(Some(mut as_file)) = fs.path(&path).as_file());
+        let_assert!(Ok(Some(as_file)) = fs.path(&path).as_file());
 
         assert_eq!(file.as_pathbuf(), as_file.as_pathbuf());
         assert_eq!(as_file.reader().expect("reader").to_string(), "contents");
@@ -70,7 +70,7 @@ mod path {
         let fs = fs::temp().expect("temp fs");
 
         let path = fs.base().join("foo");
-        let mut dir = fs.dir(&path);
+        let dir = fs.dir(&path);
         dir.create().expect("create");
 
         let_assert!(Ok(None) = fs.path(&path).as_file());
@@ -82,7 +82,7 @@ mod path {
         let fs = fs::temp().expect("temp fs");
 
         let path = fs.base().join("foo");
-        let mut file = fs.file(&path);
+        let file = fs.file(&path);
         file.write("contents").expect("create");
 
         let_assert!(Ok(None) = fs.path(&path).as_dir());
@@ -100,12 +100,12 @@ mod file {
         let fs = fs::temp().expect("temp fs");
         let pathbuf = fs.base().join("foo");
 
-        let mut file = fs.file(&pathbuf);
+        let file = fs.file(&pathbuf);
         file.write("content").expect("write");
         let c = file.reader().expect("reader").to_string();
         assert_eq!(c, "content");
 
-        let mut path = fs.path(&pathbuf);
+        let path = fs.path(&pathbuf);
         let exists = path.exists().expect("exists");
         assert!(exists);
 
@@ -120,7 +120,7 @@ mod file {
         let fs = fs::temp().expect("temp fs");
 
         let path = fs.base().join("foo");
-        let mut file = fs.file(&path);
+        let file = fs.file(&path);
         file.write("line 1\nline 2").expect("write");
 
         let reader = file.reader().expect("reader");
@@ -174,7 +174,7 @@ mod dir_create_all {
 
         fs.dir(&pathbuf).create_all().expect("create_all");
 
-        let mut path = fs.path(&pathbuf);
+        let path = fs.path(&pathbuf);
         let exists = path.exists().expect("exists");
         assert!(exists, "path exists");