examples/get.rs

@@ -10,8 +10,6 @@
 /// `example-readme.md` in the current directory.
 use std::path::Path;
 
-use kxio::fs::FileHandle;
-
 #[tokio::main]
 async fn main() -> kxio::Result<()> {
     // Create a `Net` object for making real network requests.
@@ -29,7 +27,7 @@ async fn main() -> kxio::Result<()> {
     let file_path = fs.base().join("example-readme.md");
 
     // Create a generic handle for the file. This doesn't open the file, and always succeeds.
-    let path = fs.path(&file_path);
+    let path: kxio::fs::PathReal<kxio::fs::PathMarker> = fs.path(&file_path);
 
     // Other options are;
     // `fs.file(&file_path)` - for a file
@@ -37,16 +35,17 @@ async fn main() -> kxio::Result<()> {
 
     // Checks if the path exists (whether a file, directory, etc)
     if path.exists()? {
-        eprintln!("The file {path} already exists. Aborting!");
+        // extracts the path from the handle
+        let pathbuf = path.as_pathbuf();
+        eprintln!("The file {} already exists. Aborting!", pathbuf.display());
         return Ok(());
     }
 
     // Passes a reference to the `fs` and `net` objects for use by your program.
     // Your programs should not know whether they are handling a mock or the real thing.
     // Any file or network access should be made using these handlers to be properly testable.
-    let file = download_and_save_to_file(url, &file_path, &fs, &net).await?;
+    download_and_save_to_file(url, &file_path, &fs, &net).await?;
-    read_file(&file)?;
+    delete_file(&file_path, &fs)?;
-    delete_file(file)?;
 
     Ok(())
 }
@@ -55,50 +54,50 @@ async fn main() -> kxio::Result<()> {
 async fn download_and_save_to_file(
     url: &str,
     file_path: &Path,
-    // The filesystem abstraction
+    // The file system abstraction
     fs: &kxio::fs::FileSystem,
     // The network abstraction
     net: &kxio::net::Net,
-) -> kxio::Result<FileHandle> {
+) -> kxio::Result<()> {
     println!("fetching: {url}");
 
-    // Makes a GET request that can be mocked in a test
+    // Rather than calling `.build().send()?` on the request, pass it to the `net`
-    let response: reqwest::Response = net.get(url).header("key", "value").send().await?;
+    // This allows the `net` to either make the network request as normal, or, if we are
-
+    // under test, to handle the request as the test dictates.
-    // As you can see, we use [reqwest] under the hood.
+    // NOTE: if the `.build().send()` is called on the `request` then that WILL result in
+    // a real network request being made, even under test conditions. Only ever use the
+    // `net.send(...)` function to keep your code testable.
+    // `kxio::net::Response` is an alias for `reqwest::Response`.
+    let response: kxio::net::Response = net.get(url).header("key", "value").send().await?;
+    // Other options:
+    //   Uses the network abstraction to create a perfectly normal `reqwest::ResponseBuilder`.
+    //   `kxio::net::RequestBuilder` is an alias.
+    // let response = net.send(net.client().get(url)).await?;
     //
-    // If you need to create a more complex request than the [kxio] fluent API allows, you
+    // let response = net.post(url).body("{}").send().await?;
-    // can create a request using [reqwest] and pass it to [net.send(request)].
 
     let body = response.text().await?;
     println!("fetched {} bytes", body.bytes().len());
 
+    println!("writing file: {}", file_path.display());
     // Uses the file system abstraction to create a handle for a file.
     let file: kxio::fs::PathReal<kxio::fs::FileMarker> = fs.file(file_path);
-    println!("writing file: {file}");
     // Writes the body to the file.
     file.write(body)?;
 
-    Ok(file)
-}
-
-/// A function that reads the file contents
-fn read_file(file: &FileHandle) -> kxio::Result<()> {
-    println!("reading file: {file}");
-
-    // Creates a `Reader` which loaded the file into memory.
-    let reader: kxio::fs::Reader = file.reader()?;
-    let contents: &str = reader.as_str();
-    println!("{contents}");
-
     Ok(())
 }
 
-/// A function that deletes the file
+/// An function that uses a `FileSystem` object to interact with the outside world.
-fn delete_file(file: FileHandle) -> kxio::Result<()> {
+fn delete_file(file_path: &Path, fs: &kxio::fs::FileSystem) -> kxio::Result<()> {
-    println!("deleting file: {file}");
+    println!("reading file: {}", file_path.display());
 
-    file.remove()?;
+    // Uses the file system abstraction to create a handle for a file.
+    let file: kxio::fs::PathReal<kxio::fs::FileMarker> = fs.file(file_path);
+    // Creates a `Reader` which loaded the file into memory.
+    let reader: kxio::fs::Reader = file.reader()?;
+    let contents: &str = reader.as_str();
+    println!("{contents}");
 
     Ok(())
 }

src/fs/dir.rs

@@ -1,5 +1,3 @@
-use std::fmt::Display;
-
 //
 use crate::fs::{DirItem, DirItemIterator, Result};
 
@@ -108,9 +106,3 @@ impl TryFrom<PathHandle<PathMarker>> for DirHandle {
         }
     }
 }
-
-impl Display for DirHandle {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}/", self.as_pathbuf().display())
-    }
-}

src/fs/file.rs

@@ -1,9 +1,7 @@
-use std::fmt::Display;
-
 //
 use crate::fs::Result;
 
-use super::{reader::Reader, Error, FileHandle, FileMarker, PathHandle, PathMarker, PathReal};
+use super::{reader::Reader, Error, FileHandle, PathHandle, PathMarker};
 
 impl FileHandle {
     /// Returns a [Reader] for the file.
@@ -114,9 +112,3 @@ impl TryFrom<PathHandle<PathMarker>> for FileHandle {
         }
     }
 }
-
-impl Display for PathReal<FileMarker> {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", self.as_pathbuf().display())
-    }
-}

src/fs/path.rs

@@ -1,6 +1,5 @@
 //
 use std::{
-    fmt::Display,
     marker::PhantomData,
     path::{Path, PathBuf},
 };
@@ -368,9 +367,3 @@ impl From<FileHandle> for PathHandle<PathMarker> {
         PathReal::new(file.base, file.path)
     }
 }
-
-impl Display for PathReal<PathMarker> {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "{}", self.as_pathbuf().display())
-    }
-}

src/net/system.rs

@@ -97,9 +97,6 @@ impl Net {
     /// then the request will be matched and any stored response returned, or an
     /// error if no matched request was found.
     ///
-    /// This method provides an escape-hatch from `kxio`'s fluent API, and allows you
-    /// to create a request using [reqwest] directly.
-    ///
     /// # Errors
     ///
     /// This method fails if there was an error while sending request,

tests/fs.rs

@@ -16,14 +16,6 @@ mod path {
 
         assert_eq!(read.base(), fs.base());
     }
-
-    #[test]
-    fn display() {
-        let fs = fs::temp().expect("temp fs");
-        let path = fs.base().join("foo");
-        let path_handle = fs.path(&path);
-        assert_eq!(path_handle.to_string(), format!("{}", path.display()));
-    }
     mod is_link {
         use super::*;
 
@@ -464,13 +456,20 @@ mod path {
 mod file {
     use super::*;
 
-    #[test]
+    // // test for reading the symlink metadata
-    fn display() {
+    // #[test]
-        let fs = fs::temp().expect("temp fs");
+    // fn symlink_metadata() -> TestResult {
-        let path = fs.base().join("foo");
+    //     let fs = fs::temp().expect("temp fs");
-        let file_handle = fs.file(&path);
+    //     let file_path = fs.base().join("foo");
-        assert_eq!(file_handle.to_string(), format!("{}", path.display()));
+    //     let file = fs.file(&file_path);
-    }
+    //     file.write("bar").expect("write");
+    //     let link_path = fs.base().join("bar");
+    //     let link = fs.path(&link_path);
+    //     file.soft_link(&link).expect("soft_link");
+    //     let md = link.symlink_metadata().expect("symlink metadata");
+    //     assert!(md.is_file());
+    //     Ok(())
+    // }
 
     #[test]
     fn create_hard_link() -> TestResult {
@@ -794,14 +793,6 @@ mod dir {
 
         use super::*;
 
-        #[test]
-        fn display() {
-            let fs = fs::temp().expect("temp fs");
-            let path = fs.base().join("foo");
-            let dir_handle = fs.dir(&path);
-            assert_eq!(dir_handle.to_string(), format!("{}/", path.display()));
-        }
-
         #[test]
         fn path_is_dir() {
             let fs = fs::temp().expect("temp fs");