kemitix/kxio
1
0
Fork 0
Code Issues 2 Pull requests Releases 13 Activity Actions

feat: remove need for mutability
All checks were successful
Rust / build (map[name:stable]) (push) Successful in 1m54s
Details
Rust / build (map[name:nightly]) (push) Successful in 3m38s
Details
Release Please / Release-plz (push) Successful in 1m25s
Details

Browse source 
adds rustdocs
This commit is contained in:
Paul Campbell 2024-11-02 12:48:09 +00:00
parent d2ee798f25
commit 76d75cabd9
9 changed files with 274 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
justfile
View file

@ -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"

76
src/fs/dir.rs
View file

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

32
src/fs/file.rs
View file

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

2
src/fs/mod.rs
View file

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

107
src/fs/path.rs
View file

@ -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<()> {
if let Some(error) = self.error.take() {
return Err(error);
}
pub(super) fn check_error(&self) -> Result<()> {
if let Some(error) = &self.error {
Err(error.clone())
} else {
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)))

50
src/fs/reader.rs
View file

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

15
src/fs/result.rs
View file

@ -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.
///

2
src/fs/system.rs
View file

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

18
tests/fs.rs
View file

@ -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");