Feature/granular errors

Cargo.toml

@@ -15,6 +15,7 @@ repository = "https://github.com/muja/unrar.rs"
 regex = "1"
 bitflags = "1"
 widestring = "1"
+thiserror = "1.0.50"
 
 [dependencies.unrar_sys]
 path = "unrar_sys"

README.md

@@ -100,15 +100,14 @@ For more sophisticated examples, please look inside the `examples/` folder.
 Here's what a function that returns the first content of a file could look like:
 
 ```rust
-fn first_file_content<P: AsRef<Path>>(path: P) -> UnrarResult<Vec<u8>> {
-    let archive = Archive::new(&path).open_for_processing()?; // cursor: before header
+fn first_file_content<P: AsRef<Path>>(path: P) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
+    let archive = unrar::Archive::new(&path).open_for_processing()?; // cursor: before header
     let archive = archive.read_header()?.expect("empty archive"); // cursor: before file
     dbg!(&archive.entry().filename);
     let (data, _rest) = archive.read()?; // cursor: before header
     Ok(data)
 }
 # use std::path::Path;
-# use unrar::{Archive, UnrarResult};
 #
 # let data = first_file_content("data/version.rar").unwrap();
 # assert_eq!(std::str::from_utf8(&data), Ok("unrar-0.4.0"));

examples/basic_extract.rs

@@ -1,10 +1,9 @@
 use unrar::Archive;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let mut archive =
-        Archive::new("../archive.rar")
-            .open_for_processing()
-            .unwrap();
+    let args = std::env::args();
+    let file = args.skip(1).next().unwrap_or("archive.rar".to_owned());
+    let mut archive = Archive::new(&file).open_for_processing().unwrap();
     while let Some(header) = archive.read_header()? {
         println!(
             "{} bytes: {}",

examples/read_named.rs

@@ -1,6 +1,6 @@
-use unrar::{Archive, UnrarResult};
+use unrar::Archive;
 
-fn main() -> UnrarResult<()> {
+fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Basic args parsing
     // Usage: cargo run --example extract_named <archive> <entry-filename-to-print>
     let mut args = std::env::args_os().skip(1);

src/archive.rs

@@ -1,4 +1,5 @@
-use crate::error::*;
+use crate::Nulable;
+use crate::OpenError;
 use crate::open_archive::{CursorBeforeHeader, List, ListSplit, OpenArchive, OpenMode, Process};
 use regex::Regex;
 use std::borrow::Cow;
@@ -323,21 +324,29 @@ impl<'a> Archive<'a> {
     ///
     /// See also: [`Process`]
     ///
-    /// # Panics
+    /// # Errors
     ///
-    /// Panics if `self.filename` contains nul values.
-    pub fn open_for_processing(self) -> UnrarResult<OpenArchive<Process, CursorBeforeHeader>> {
+    /// - `NulError` if `self.filename` or `self.password` contains nul values.
+    /// - `RarError` if there was an error opening/reading/decoding the archive.
+    ///
+    pub fn open_for_processing(
+        self,
+    ) -> Result<OpenArchive<Process, CursorBeforeHeader>, Nulable<OpenError>> {
         self.open(None)
     }
 
     /// Opens the underlying archive for listing its entries, i.e. the payloads are skipped automatically.
     ///
     /// See also: [`List`]
     ///
-    /// # Panics
+    /// # Errors
+    ///
+    /// - `NulError` if `self.filename` or `self.password` contains nul values.
+    /// - `RarError` if there was an error opening/reading/decoding the archive.
     ///
-    /// Panics if `self.filename` contains nul values.
-    pub fn open_for_listing(self) -> UnrarResult<OpenArchive<List, CursorBeforeHeader>> {
+    pub fn open_for_listing(
+        self,
+    ) -> Result<OpenArchive<List, CursorBeforeHeader>, Nulable<OpenError>> {
         self.open(None)
     }
 
@@ -348,23 +357,22 @@ impl<'a> Archive<'a> {
     ///
     /// See also: [`ListSplit`]
     ///
-    /// # Panics
+    /// # Errors
     ///
-    /// Panics if `self.filename` contains nul values.
-
-    pub fn open_for_listing_split(self) -> UnrarResult<OpenArchive<ListSplit, CursorBeforeHeader>> {
+    /// - `NulError` if `self.filename` or `self.password` contains nul values.
+    /// - `RarError` if there was an error opening/reading/decoding the archive.
+    ///
+    pub fn open_for_listing_split(
+        self,
+    ) -> Result<OpenArchive<ListSplit, CursorBeforeHeader>, Nulable<OpenError>> {
         self.open(None)
     }
 
     /// Opens the underlying archive with the provided parameters.
-    ///
-    /// # Panics
-    ///
-    /// Panics if `path` contains nul values.
     fn open<M: OpenMode>(
         self,
         recover: Option<&mut Option<OpenArchive<M, CursorBeforeHeader>>>,
-    ) -> UnrarResult<OpenArchive<M, CursorBeforeHeader>> {
+    ) -> Result<OpenArchive<M, CursorBeforeHeader>, Nulable<OpenError>> {
         OpenArchive::new(&self.filename, self.password, recover)
     }
 
@@ -378,8 +386,8 @@ impl<'a> Archive<'a> {
     /// # Example: I don't care if there was a recoverable error
     ///
     /// ```no_run
-    /// # use unrar::{Archive, List, UnrarResult};
-    /// # fn x() -> UnrarResult<()> {
+    /// # use unrar::{Archive, List};
+    /// # fn x() -> Result<(), unrar::Nulable<unrar::OpenError>> {
     /// let mut open_archive = Archive::new("file").break_open::<List>(None)?;
     /// // use open_archive
     /// # Ok(())
@@ -389,8 +397,8 @@ impl<'a> Archive<'a> {
     /// # Example: I want to know if there was a recoverable error
     ///
     /// ```no_run
-    /// # use unrar::{Archive, List, UnrarResult};
-    /// # fn x() -> UnrarResult<()> {
+    /// # use unrar::{Archive, List};
+    /// # fn x() -> Result<(), unrar::Nulable<unrar::OpenError>> {
     /// let mut possible_error = None;
     /// let mut open_archive = Archive::new("file").break_open::<List>(Some(&mut possible_error))?;
     /// // check the error, e.g.:
@@ -400,21 +408,23 @@ impl<'a> Archive<'a> {
     /// # }
     /// ```
     ///
-    /// # Panics
+    /// # Errors
+    ///
+    /// - `NulError` if `self.filename` or `self.password` contains nul values.
+    /// - `RarError` if there was an error opening/reading/decoding the archive.
     ///
-    /// Panics if `path` contains nul values.
     pub fn break_open<M: OpenMode>(
         self,
-        error: Option<&mut Option<UnrarError>>,
-    ) -> UnrarResult<OpenArchive<M, CursorBeforeHeader>> {
+        error: Option<&mut Option<OpenError>>,
+    ) -> Result<OpenArchive<M, CursorBeforeHeader>, Nulable<OpenError>> {
         let mut recovered = None;
         self.open(Some(&mut recovered))
-            .or_else(|x| match recovered {
-                Some(archive) => {
-                    error.map(|error| *error = Some(x));
+            .or_else(|e| match (recovered, e) {
+                (Some(archive), Nulable::Rar(e)) => {
+                    error.map(|error| *error = Some(e));
                     Ok(archive)
                 }
-                None => Err(x),
+                (_, _) => Err(e),
             })
     }
 }