[Enhancement] Truncate Optional PathBuf-like Instances (#85)

* Added ::= OptionTruncation

* Added::= OptionTruncation::truncate_silently

* Added ::= OptionTruncation::truncate_loudly

* Added ::= tests for OptionTruncation

* Skip ::= fix typo

* Create summary of recent changes

---------

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>

changelog.d/20240128_190857_GitHub_Actions_option-truncation.ron

@@ -0,0 +1,11 @@
+(
+  references: {},
+  changes: {
+    "Added": [
+      "OptionTruncation",
+      "OptionTruncation::truncate_loudly",
+      "OptionTruncation::truncate_silently",
+      "tests for OptionTruncation",
+    ],
+  },
+)

src/lib.rs

@@ -132,7 +132,7 @@ mod reading;
 mod writing;
 
 pub use reading::{BufReadReader, OptionReader, PathBufLikeReader};
-pub use writing::{PathBufLikeTruncation, Writer};
+pub use writing::{OptionTruncation, PathBufLikeTruncation, Writer};
 
 /// This crate's name.
 pub const NAME: &str = "aeruginous-io";

src/writing.rs

@@ -120,10 +120,84 @@ where
     }
 }
 
+/// Truncate either destination, depending on the circumstances.
+pub trait OptionTruncation<P, W>
+where
+    PathBuf: From<P>,
+    W: Write,
+{
+    /// Truncate either destination, depending on the circumstances.
+    ///
+    /// This method behaves just like
+    /// [`crate::OptionTruncation::truncate_silently`] despite also printing
+    /// error messages to [`std::io::Stderr`].
+    ///
+    /// # Errors
+    ///
+    /// See [`sysexits::ExitCode`].
+    fn truncate_loudly(
+        self,
+        destination: Option<P>,
+        alternative: W,
+    ) -> Result<()>;
+
+    /// Truncate either destination, depending on the circumstances.
+    ///
+    /// The data this method is called on will be converted to a [`String`] and
+    /// written to either source.  The data therefore needs to implement
+    /// [`ToString`].  If the default destination is [`Some`], it will be
+    /// truncated by [`crate::PathBufLikeTruncation::truncate_silently`].  The
+    /// default destination therefore needs to implement
+    /// [`crate::PathBufLikeTruncation`].  If the default
+    /// destination is [`None`], the alternative will be used as output stream.
+    /// The alternative therefore needs to implement [`crate::Writer`].
+    ///
+    /// The return value is either the unit type, in case of success, or a
+    /// [`sysexits::ExitCode`] to describe the error cause, otherwise.
+    ///
+    /// Error messages are not written to [`std::io::Stderr`].
+    ///
+    /// # Errors
+    ///
+    /// See [`sysexits::ExitCode`].
+    fn truncate_silently(
+        self,
+        destination: Option<P>,
+        alternative: W,
+    ) -> Result<()>;
+}
+
+impl<P, W: Write, T: ToString> OptionTruncation<P, W> for T
+where
+    PathBuf: From<P>,
+{
+    fn truncate_loudly(
+        self,
+        destination: Option<P>,
+        alternative: W,
+    ) -> Result<()> {
+        match destination {
+            Some(p) => PathBufLikeTruncation::truncate_loudly(self, p),
+            None => self.write_loudly(alternative),
+        }
+    }
+
+    fn truncate_silently(
+        self,
+        destination: Option<P>,
+        alternative: W,
+    ) -> Result<()> {
+        match destination {
+            Some(p) => PathBufLikeTruncation::truncate_silently(self, p),
+            None => self.write_silently(alternative),
+        }
+    }
+}
+
 /// Write to a [`std::io::Write`]r.
 pub trait Writer<T>
 where
-    T: std::io::Write,
+    T: Write,
 {
     /// Write the data this method is called on to the given destination.
     ///

tests/writing.rs

@@ -101,6 +101,50 @@ mod path_buf_like_truncation {
     }
 }
 
+mod option_truncation {
+    use aeruginous_io::{OptionTruncation, PathBufLikeReader};
+
+    #[test]
+    fn truncate_loudly_success_none() {
+        let mut buffer = Vec::new();
+
+        assert!("test"
+            .truncate_loudly(None::<std::path::PathBuf>, &mut buffer)
+            .is_ok());
+        assert_eq!(buffer, b"test");
+    }
+
+    #[test]
+    fn truncate_loudly_success_some() {
+        let f = "option_truncation_truncate_loudly_success_some.txt";
+
+        assert!("test\n".truncate_loudly(Some(f), &mut Vec::new()).is_ok());
+        assert_eq!(f.read_silently().unwrap(), "test\n");
+
+        std::fs::remove_file(f).unwrap();
+    }
+
+    #[test]
+    fn truncate_silently_success_none() {
+        let mut buffer = Vec::new();
+
+        assert!("test"
+            .truncate_silently(None::<std::path::PathBuf>, &mut buffer)
+            .is_ok());
+        assert_eq!(buffer, b"test");
+    }
+
+    #[test]
+    fn truncate_silently_success_some() {
+        let f = "option_truncation_truncate_silently_success_some.txt";
+
+        assert!("test\n".truncate_silently(Some(f), &mut Vec::new()).is_ok());
+        assert_eq!(f.read_silently().unwrap(), "test\n");
+
+        std::fs::remove_file(f).unwrap();
+    }
+}
+
 mod writer {
     use aeruginous_io::Writer;