refactor: use generics for path type

src/fs/dir.rs

@@ -0,0 +1,22 @@
+//
+use crate::fs::{DirItem, DirItemIterator, Result};
+
+use super::path::{DirG, PathReal};
+
+impl<'base, 'path> PathReal<'base, 'path, DirG> {
+    pub fn create(&mut self) -> Result<()> {
+        self.check_error()?;
+        std::fs::create_dir(self.as_pathbuf()).map_err(Into::into)
+    }
+
+    pub fn create_all(&mut 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>>>> {
+        self.check_error()?;
+        let read_dir = std::fs::read_dir(self.as_pathbuf())?;
+        Ok(Box::new(DirItemIterator::new(read_dir)))
+    }
+}

src/fs/dir_item.rs

@@ -1,8 +1,10 @@
+//
 use std::{
     fs::{DirEntry, ReadDir},
     path::PathBuf,
 };
 
+/// Represents an item in a directory
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord)]
 pub enum DirItem {
     File(PathBuf),
@@ -12,6 +14,7 @@ pub enum DirItem {
     Unsupported(PathBuf),
 }
 
+/// An iterator for items in a directory.
 #[derive(Debug, derive_more::Constructor)]
 pub struct DirItemIterator(ReadDir);
 impl Iterator for DirItemIterator {

src/fs/file.rs

@@ -0,0 +1,19 @@
+//
+use crate::fs::Result;
+
+use super::{
+    path::{FileG, PathReal},
+    reader::ReaderReal,
+};
+
+impl<'base, 'path> PathReal<'base, 'path, FileG> {
+    pub fn reader(&mut self) -> Result<ReaderReal> {
+        self.check_error()?;
+        ReaderReal::new(&self.as_pathbuf())
+    }
+
+    pub fn write(&mut self, contents: &str) -> Result<()> {
+        self.check_error()?;
+        std::fs::write(self.as_pathbuf(), contents).map_err(Into::into)
+    }
+}

src/fs/mod.rs

@@ -1,18 +1,46 @@
+/// Provides an injectable reference to part of the filesystem.
+///
+/// Create a new `FileSystem` to access a directory using `kxio::fs::new(path)`.
+/// Create a new `TempFileSystem` to access a temporary directory using `kxio::fs::temp()?`;
+///
+/// `TempFileSystem` derefs automaticalyl to `FileSystem` so can be used anywhere
+/// you would use `FileSystem`.
 use std::path::PathBuf;
 
+mod dir;
 mod dir_item;
-mod real;
+mod file;
+mod path;
+mod reader;
 mod result;
+mod system;
 mod temp;
 
-pub use dir_item::DirItem;
+pub use dir_item::{DirItem, DirItemIterator};
-pub use dir_item::DirItemIterator;
 pub use result::{Error, Result};
+pub use system::FileSystem;
 
-pub const fn new(base: PathBuf) -> real::FileSystem {
+/// Creates a new `FileSystem` for the path.
-    real::FileSystem::new(base)
+///
+/// This will create a `FileSystem` that provides access to the
+/// filesystem under the given path.
+///
+/// Any attempt to access outside this base will result in a
+/// `error::Error::PathTraversal` error when attempting the
+/// opertation.
+pub const fn new(base: PathBuf) -> FileSystem {
+    FileSystem::new(base)
 }
 
+/// Creates a new `TempFileSystem` for a temporary directory.
+///
+/// The `TempFileSystem` provides a `Deref` to a `FileSystem` for
+/// the temporary directory.
+///
+/// When the `TempFileSystem` is dropped, the temporary directory
+/// is deleted.
+///
+/// Returns an error if the temporary directory cannot be created.
 pub fn temp() -> Result<temp::TempFileSystem> {
     temp::TempFileSystem::new()
 }

src/fs/path.rs

@@ -1,27 +1,51 @@
 //
-use std::path::{Path, PathBuf};
+use std::{
+    marker::PhantomData,
+    path::{Path, PathBuf},
+};
 
 use crate::fs::{Error, Result};
 
-use super::{dir::DirReal, file::FileReal};
+pub trait PathType {}
+
+pub struct PathG;
+impl PathType for PathG {}
+
+pub struct FileG;
+impl PathType for FileG {}
+
+pub struct DirG;
+impl PathType for DirG {}
 
 #[derive(Debug)]
-pub struct PathReal<'base, 'path> {
+pub struct PathReal<'base, 'path, T: PathType> {
     base: &'base Path,
     path: &'path Path,
+    _phanton: PhantomData<T>,
     pub(super) error: Option<Error>,
 }
-impl<'base, 'path> PathReal<'base, 'path> {
+impl<'base, 'path, T: PathType> PathReal<'base, 'path, T> {
-    pub(super) fn full_path(&self) -> PathBuf {
+    pub(super) fn new(base: &'base Path, path: &'path Path) -> Self {
+        Self {
+            base,
+            path,
+            _phanton: PhantomData::<T>,
+            error: PathReal::<T>::validate(base, path),
+        }
+    }
+
+    pub fn as_pathbuf(&self) -> PathBuf {
         self.base.join(self.path)
     }
+
     pub(super) fn put(&mut self, error: Error) {
         if self.error.is_none() {
             self.error.replace(error);
         }
     }
+
     fn validate(base: &Path, path: &Path) -> Option<Error> {
-        match PathReal::clean_path(path) {
+        match PathReal::<PathG>::clean_path(path) {
             Err(error) => Some(error),
             Ok(path) => {
                 if !path.starts_with(base) {
@@ -47,19 +71,6 @@ impl<'base, 'path> PathReal<'base, 'path> {
         Ok(abs_path)
     }
 
-    pub(super) fn new(base: &'base Path, path: &'path Path) -> Self {
-        Self {
-            base,
-            path,
-            error: PathReal::validate(base, path),
-        }
-    }
-
-    pub fn exists(&mut self) -> Result<bool> {
-        self.check_error()?;
-        Ok(self.full_path().exists())
-    }
-
     pub(super) fn check_error(&mut self) -> Result<()> {
         if let Some(error) = self.error.take() {
             return Err(error);
@@ -67,36 +78,41 @@ impl<'base, 'path> PathReal<'base, 'path> {
         Ok(())
     }
 
+    pub fn exists(&mut self) -> Result<bool> {
+        self.check_error()?;
+        Ok(self.as_pathbuf().exists())
+    }
+
     pub fn is_dir(&mut self) -> Result<bool> {
         self.check_error()?;
-        Ok(self.full_path().is_dir())
+        Ok(self.as_pathbuf().is_dir())
     }
 
     pub fn is_file(&mut self) -> Result<bool> {
         self.check_error()?;
-        Ok(self.full_path().is_file())
+        Ok(self.as_pathbuf().is_file())
     }
 
-    pub fn as_dir(&mut self) -> Result<Option<DirReal<'base, 'path>>> {
+    pub fn as_dir(&mut self) -> Result<Option<PathReal<'base, 'path, DirG>>> {
         self.check_error()?;
-        if self.full_path().is_dir() {
+        if self.as_pathbuf().is_dir() {
-            Ok(Some(DirReal::new(self.base, self.path)))
+            Ok(Some(PathReal::new(self.base, self.path)))
         } else {
             Ok(None)
         }
     }
 
-    pub fn as_file(&mut self) -> Result<Option<FileReal<'base, 'path>>> {
+    pub fn as_file(&mut self) -> Result<Option<PathReal<'base, 'path, FileG>>> {
         self.check_error()?;
-        if self.full_path().is_file() {
+        if self.as_pathbuf().is_file() {
-            Ok(Some(FileReal::new(self.base, self.path)))
+            Ok(Some(PathReal::new(self.base, self.path)))
         } else {
             Ok(None)
         }
     }
 }
-impl From<PathReal<'_, '_>> for PathBuf {
+impl From<PathReal<'_, '_, PathG>> for PathBuf {
-    fn from(path: PathReal) -> Self {
+    fn from(path: PathReal<PathG>) -> Self {
         path.base.join(path.path)
     }
 }

src/fs/real/dir.rs

@@ -1,64 +0,0 @@
-//
-use std::path::{Path, PathBuf};
-
-use crate::fs::{DirItem, DirItemIterator, Error, Result};
-
-use super::path::PathReal;
-
-pub struct DirReal<'base, 'path> {
-    path: PathReal<'base, 'path>,
-}
-impl<'base, 'path> DirReal<'base, 'path> {
-    pub(super) fn new(base: &'base Path, path: &'path Path) -> Self {
-        let mut path = PathReal::new(base, path);
-        if path.error.is_none() {
-            if let Ok(exists) = path.exists() {
-                if exists {
-                    if let Ok(is_dir) = path.is_dir() {
-                        if !is_dir {
-                            path.put(Error::NotADirectory {
-                                path: path.full_path(),
-                            })
-                        }
-                    }
-                }
-            }
-        }
-        Self { path }
-    }
-
-    pub fn path(&self) -> PathBuf {
-        self.path.full_path()
-    }
-
-    pub fn create(&mut self) -> Result<()> {
-        self.path.check_error()?;
-        std::fs::create_dir(self.path.full_path()).map_err(Into::into)
-    }
-
-    pub fn create_all(&mut self) -> Result<()> {
-        self.path.check_error()?;
-        std::fs::create_dir_all(self.path.full_path()).map_err(Into::into)
-    }
-
-    pub fn read(&mut self) -> Result<Box<dyn Iterator<Item = Result<DirItem>>>> {
-        self.path.check_error()?;
-        let read_dir = std::fs::read_dir(self.path.full_path())?;
-        Ok(Box::new(DirItemIterator::new(read_dir)))
-    }
-
-    pub fn exists(&mut self) -> Result<bool> {
-        self.path.check_error()?;
-        self.path.exists()
-    }
-
-    pub fn is_dir(&mut self) -> Result<bool> {
-        self.path.check_error()?;
-        Ok(true)
-    }
-
-    pub fn is_file(&mut self) -> Result<bool> {
-        self.path.check_error()?;
-        Ok(false)
-    }
-}

src/fs/real/file.rs

@@ -1,46 +0,0 @@
-//
-use std::path::{Path, PathBuf};
-
-use crate::fs::Result;
-
-use super::{path::PathReal, reader::ReaderReal};
-
-pub struct FileReal<'base, 'path> {
-    path: PathReal<'base, 'path>,
-}
-impl<'base, 'path> FileReal<'base, 'path> {
-    pub(super) fn new(base: &'base Path, path: &'path Path) -> Self {
-        Self {
-            path: PathReal::new(base, path),
-        }
-    }
-
-    pub fn path(&self) -> PathBuf {
-        self.path.full_path()
-    }
-
-    pub fn reader(&mut self) -> Result<ReaderReal> {
-        self.path.check_error()?;
-        ReaderReal::new(&self.path.full_path())
-    }
-
-    pub fn write(&mut self, contents: &str) -> Result<()> {
-        self.path.check_error()?;
-        std::fs::write(self.path.full_path(), contents).map_err(Into::into)
-    }
-
-    pub fn exists(&mut self) -> Result<bool> {
-        self.path.check_error()?;
-        self.path.exists()
-    }
-
-    pub fn is_dir(&mut self) -> Result<bool> {
-        self.path.check_error()?;
-        Ok(false)
-    }
-
-    pub fn is_file(&mut self) -> Result<bool> {
-        self.path.check_error()?;
-        Ok(true)
-    }
-}

src/fs/real/mod.rs

@@ -1,8 +0,0 @@
-//
-mod dir;
-mod file;
-mod path;
-mod reader;
-mod system;
-
-pub use system::FileSystem;

src/fs/result.rs

@@ -3,6 +3,11 @@ use std::path::PathBuf;
 
 use derive_more::From;
 
+/// Represents a error accessing the file system.
+///
+/// Any failure is related to `std::io`, a Path Traversal
+/// (i.e. trying to escape the base of the `FileSystem`),
+/// or attempting to use a file as a directory or /vise versa/.
 #[derive(Debug, From, derive_more::Display)]
 pub enum Error {
     Io(std::io::Error),
@@ -20,4 +25,9 @@ pub enum Error {
 }
 impl std::error::Error for Error {}
 
+/// Represents a success or a failure.
+///
+/// Any failure is related to `std::io`, a Path Traversal
+/// (i.e. trying to escape the base of the `FileSystem`),
+/// or attempting to use a file as a directory or /vise versa/.
 pub type Result<T> = core::result::Result<T, Error>;

src/fs/system.rs

@@ -3,8 +3,9 @@ use std::path::{Path, PathBuf};
 
 use crate::fs::{Error, Result};
 
-use super::{dir::DirReal, file::FileReal, path::PathReal};
+use super::path::{DirG, FileG, PathG, PathReal};
 
+/// Represents to base of a section of a file system.
 #[derive(Clone, Debug)]
 pub struct FileSystem {
     base: PathBuf,
@@ -23,15 +24,31 @@ impl FileSystem {
         Ok(path_of)
     }
 
-    pub fn dir<'base, 'path>(&'base self, path: &'path Path) -> DirReal<'base, 'path> {
+    pub fn dir<'base, 'path>(&'base self, path: &'path Path) -> PathReal<'base, 'path, DirG> {
-        DirReal::new(self.base(), path)
+        let mut dir = PathReal::new(self.base(), path);
+
+        if dir.error.is_none() {
+            if let Ok(exists) = dir.exists() {
+                if exists {
+                    if let Ok(is_dir) = dir.is_dir() {
+                        if !is_dir {
+                            dir.put(Error::NotADirectory {
+                                path: dir.as_pathbuf(),
+                            })
+                        }
+                    }
+                }
+            }
+        }
+
+        dir
     }
 
-    pub fn file<'base, 'path>(&'base self, path: &'path Path) -> FileReal<'base, 'path> {
+    pub fn file<'base, 'path>(&'base self, path: &'path Path) -> PathReal<'base, 'path, FileG> {
-        FileReal::new(self.base(), path)
+        PathReal::new(self.base(), path)
     }
 
-    pub fn path<'base, 'path>(&'base self, path: &'path Path) -> PathReal<'base, 'path> {
+    pub fn path<'base, 'path>(&'base self, path: &'path Path) -> PathReal<'base, 'path, PathG> {
         PathReal::new(self.base(), path)
     }
 

src/fs/temp.rs

@@ -2,7 +2,7 @@ use std::sync::{Arc, Mutex};
 
 use tempfile::TempDir;
 
-use super::real::FileSystem;
+use super::FileSystem;
 
 #[derive(Clone, Debug)]
 pub struct TempFileSystem {

tests/fs.rs

@@ -45,7 +45,7 @@ mod path {
 
         let_assert!(Ok(Some(as_dir)) = fs.path(&path).as_dir());
 
-        assert_eq!(dir.path(), as_dir.path());
+        assert_eq!(dir.as_pathbuf(), as_dir.as_pathbuf());
 
         Ok(())
     }
@@ -60,7 +60,7 @@ mod path {
 
         let_assert!(Ok(Some(mut as_file)) = fs.path(&path).as_file());
 
-        assert_eq!(file.path(), as_file.path());
+        assert_eq!(file.as_pathbuf(), as_file.as_pathbuf());
         assert_eq!(as_file.reader().expect("reader").to_string(), "contents");
 
         Ok(())