[Enhancement] Read from Vec<PathBufLikeReader> (#95)

* Added ::= VectorReader

* Added ::= VectorReader::read_silently

* Added ::= VectorReader::read_loudly

* Added ::= tests for VectorReader

* Create summary of recent changes

---------

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

changelog.d/20240202_163408_GitHub_Actions_vector-reader.ron

@@ -0,0 +1,11 @@
+(
+  references: {},
+  changes: {
+    "Added": [
+      "VectorReader",
+      "VectorReader::read_loudly",
+      "VectorReader::read_silently",
+      "tests for VectorReader",
+    ],
+  },
+)

src/lib.rs

@@ -131,7 +131,9 @@
 mod reading;
 mod writing;
 
-pub use reading::{BufReadReader, OptionReader, PathBufLikeReader};
+pub use reading::{
+    BufReadReader, OptionReader, PathBufLikeReader, VectorReader,
+};
 pub use writing::{OptionTruncation, PathBufLikeTruncation, Writer};
 
 /// This crate's name.

src/reading.rs

@@ -192,4 +192,69 @@ where
     }
 }
 
+/// Read from a list of [`crate::PathBufLikeReader`]s.
+pub trait VectorReader<B>
+where
+    B: BufReadReader,
+{
+    /// Read from a list of [`crate::PathBufLikeReader`]s.
+    ///
+    /// This method behaves just like [`crate::VectorReader::read_silently`]
+    /// despite also printing error messages to [`std::io::Stderr`].
+    ///
+    /// # Errors
+    ///
+    /// See [`sysexits::ExitCode`].
+    fn read_loudly(&self, alternative: B) -> Result<String>;
+
+    /// Read from a list of [`crate::PathBufLikeReader`]s.
+    ///
+    /// If the instance this method is called on is a non-empty collection, each
+    /// of its elements will be read.  Therefore, the elements need to implement
+    /// [`crate::PathBufLikeReader`].  In case the instance this method is
+    /// called on is an empty collection, the alternative will be read.
+    /// Therefore, it needs to implement [`crate::BufReadReader`].
+    ///
+    /// The return value is either the read content as a [`String`], 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 read_silently(&self, alternative: B) -> Result<String>;
+}
+
+impl<B: BufReadReader, P: PathBufLikeReader> VectorReader<B> for Vec<P> {
+    fn read_loudly(&self, alternative: B) -> Result<String> {
+        if self.is_empty() {
+            alternative.read_loudly()
+        } else {
+            let mut result = String::new();
+
+            for element in self {
+                result.push_str(element.read_loudly()?.as_str());
+            }
+
+            Ok(result)
+        }
+    }
+
+    fn read_silently(&self, alternative: B) -> Result<String> {
+        if self.is_empty() {
+            alternative.read_silently()
+        } else {
+            let mut result = String::new();
+
+            for element in self {
+                result.push_str(element.read_silently()?.as_str());
+            }
+
+            Ok(result)
+        }
+    }
+}
+
 /******************************************************************************/

tests/reading.rs

@@ -162,4 +162,75 @@ mod option_reader {
     }
 }
 
+mod vector_reader {
+    use aeruginous_io::VectorReader;
+
+    #[test]
+    fn method_result_equality_empty() {
+        assert_eq!(
+            Vec::<&str>::new().read_loudly(&b"test"[..]).unwrap(),
+            Vec::<&str>::new().read_silently(&b"test"[..]).unwrap(),
+        );
+    }
+
+    #[test]
+    fn method_result_equality_non_empty() {
+        assert_eq!(
+            vec!["tests/assets/GPL-3.0.rs", "tests/assets/GPL-3.0.rs"]
+                .read_loudly(&b""[..])
+                .unwrap(),
+            vec!["tests/assets/GPL-3.0.rs", "tests/assets/GPL-3.0.rs"]
+                .read_silently(&b""[..])
+                .unwrap(),
+        );
+    }
+
+    #[test]
+    fn read_silently_success_empty() {
+        assert_eq!(
+            Vec::<&str>::new().read_silently(&b"test"[..]).unwrap(),
+            "test\n"
+        );
+    }
+
+    #[test]
+    fn read_silently_success_non_empty() {
+        assert_eq!(
+            vec!["tests/assets/GPL-3.0.rs", "tests/assets/GPL-3.0.rs"]
+                .read_silently(&b""[..])
+                .unwrap(),
+            "\
+/// Copyright (C) 2024 Kevin Matthes
+///
+/// This program is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU General Public License as published by
+/// the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// This program is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+/// GNU General Public License for more details.
+///
+/// You should have received a copy of the GNU General Public License
+/// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+/// Copyright (C) 2024 Kevin Matthes
+///
+/// This program is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU General Public License as published by
+/// the Free Software Foundation, either version 3 of the License, or
+/// (at your option) any later version.
+///
+/// This program is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+/// GNU General Public License for more details.
+///
+/// You should have received a copy of the GNU General Public License
+/// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"
+        );
+    }
+}
+
 /******************************************************************************/