Add more ergonomic ways to deal with uefi-rs' Results

Author: HadrienG2

src/error/completion.rs

@@ -0,0 +1,99 @@
+use super::Status;
+use log::warn;
+
+/// This type is used when an UEFI operation has completed, but some non-fatal
+/// problems may have been encountered along the way
+#[must_use]
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Completion<T> {
+    /// The operation completed without problems
+    Success(T),
+
+    /// The operation completed, but some non-fatal issues were encountered
+    Warning(T, Status),
+}
+
+impl<T> Completion<T> {
+    /// Split the completion into a (status, value) pair
+    pub fn split(self) -> (T, Status) {
+        match self {
+            Completion::Success(res) => (res, Status::SUCCESS),
+            Completion::Warning(res, stat) => (res, stat),
+        }
+    }
+
+    /// Access the inner value, logging the warning if there is any
+    pub fn value(self) -> T {
+        match self {
+            Completion::Success(res) => res,
+            Completion::Warning(res, stat) => {
+                warn!("Encountered UEFI warning: {:?}", stat);
+                res
+            }
+        }
+    }
+
+    /// Assume that no warning occured, panic if not
+    pub fn unwrap(self) -> T {
+        match self {
+            Completion::Success(res) => res,
+            Completion::Warning(_, w) => {
+                unwrap_failed("Called `Completion::unwrap()` on a `Warning` value", w)
+            }
+        }
+    }
+
+    /// Assume that no warning occured, panic with provided message if not
+    pub fn expect(self, msg: &str) -> T {
+        match self {
+            Completion::Success(res) => res,
+            Completion::Warning(_, w) => unwrap_failed(msg, w),
+        }
+    }
+
+    /// Transform the inner value without unwrapping the Completion
+    pub fn map<U>(self, f: impl Fn(T) -> U) -> Completion<U> {
+        match self {
+            Completion::Success(res) => Completion::Success(f(res)),
+            Completion::Warning(res, stat) => Completion::Warning(f(res), stat),
+        }
+    }
+
+    /// Merge this completion with a success or warning status
+    ///
+    /// Since this type only has storage for one warning, if two warnings must
+    /// be stored, one of them will be spilled into the logs.
+    ///
+    pub fn with_warning(self, extra_stat: Status) -> Self {
+        match self {
+            Completion::Success(res) => {
+                if extra_stat.is_success() {
+                    Completion::Success(res)
+                } else {
+                    Completion::Warning(res, extra_stat)
+                }
+            }
+            Completion::Warning(res, stat) => {
+                if extra_stat.is_success() {
+                    Completion::Warning(res, stat)
+                } else {
+                    warn!("Encountered UEFI warning {:?}", stat);
+                    Completion::Warning(res, extra_stat)
+                }
+            }
+        }
+    }
+}
+
+impl<T> From<T> for Completion<T> {
+    fn from(res: T) -> Self {
+        Completion::Success(res)
+    }
+}
+
+// This is a separate function to reduce the code size of the methods
+#[inline(never)]
+#[cold]
+fn unwrap_failed(msg: &str, warning: Status) -> ! {
+    panic!("{}: {:?}", msg, warning)
+}

src/error/mod.rs

@@ -1,106 +1,48 @@
-use core::result;
-use log::warn;
-
 /// Definition of UEFI's standard status codes
 mod status;
 pub use self::status::Status;
 
-/// This type is used when an UEFI operation has completed, but some non-fatal
-/// problems may have been encountered along the way
-#[must_use]
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub enum Completion<T> {
-    /// The operation completed without problems
-    Success(T),
+/// Completions are used to model operations which have completed, but may have
+/// encountered non-fatal errors ("warnings") along the way
+mod completion;
+pub use self::completion::Completion;
 
-    /// The operation completed, but some non-fatal issues were encountered
-    Warning(T, Status),
-}
+/// Return type of many UEFI functions.
+pub type Result<T> = core::result::Result<Completion<T>, Status>;
 
-impl<T> Completion<T> {
-    /// Split the completion into a (status, value) pair
-    pub fn split(self) -> (T, Status) {
-        match self {
-            Completion::Success(res) => (res, Status::SUCCESS),
-            Completion::Warning(res, stat) => (res, stat),
-        }
-    }
+/// Extension trait for Result which helps dealing with UEFI's warnings
+pub trait ResultExt<T> {
+    /// Treat warnings as errors
+    fn warn_error(self) -> core::result::Result<T, Status>;
 
-    /// Access the inner value, logging the warning if there is any
-    pub fn value(self) -> T {
-        match self {
-            Completion::Success(res) => res,
-            Completion::Warning(res, stat) => {
-                warn!("Encountered UEFI warning: {:?}", stat);
-                res
-            }
-        }
-    }
+    /// Ignore warnings, keepint a trace of them in the logs
+    fn warn_log(self) -> core::result::Result<T, Status>;
 
-    /// Assume that no warning occured, panic if not
-    pub fn unwrap(self) -> T {
-        match self {
-            Completion::Success(res) => res,
-            Completion::Warning(_, w) => {
-                unwrap_failed("Called `Completion::unwrap()` on a `Warning` value", w)
-            }
-        }
-    }
+    /// Expect success without warnings, panic otherwise
+    fn warn_unwrap(self) -> T;
 
-    /// Assume that no warning occured, panic with provided message if not
-    pub fn expect(self, msg: &str) -> T {
-        match self {
-            Completion::Success(res) => res,
-            Completion::Warning(_, w) => unwrap_failed(msg, w),
-        }
-    }
+    /// Expect success without warnings, panic with provided message otherwise
+    fn warn_expect(self, msg: &str) -> T;
+}
 
-    /// Transform the inner value without unwrapping the Completion
-    pub fn map<U>(self, f: impl Fn(T) -> U) -> Completion<U> {
+impl<T> ResultExt<T> for Result<T> {
+    fn warn_error(self) -> core::result::Result<T, Status> {
         match self {
-            Completion::Success(res) => Completion::Success(f(res)),
-            Completion::Warning(res, stat) => Completion::Warning(f(res), stat),
+            Ok(Completion::Success(v)) => Ok(v),
+            Ok(Completion::Warning(_, s)) => Err(s),
+            Err(s) => Err(s),
         }
     }
 
-    /// Merge this completion with a success or warning status
-    ///
-    /// Since this type only has storage for one warning, if two warnings must
-    /// be stored, one of them will be spilled into the logs.
-    ///
-    pub fn with_warning(self, extra_stat: Status) -> Self {
-        match self {
-            Completion::Success(res) => {
-                if extra_stat.is_success() {
-                    Completion::Success(res)
-                } else {
-                    Completion::Warning(res, extra_stat)
-                }
-            }
-            Completion::Warning(res, stat) => {
-                if extra_stat.is_success() {
-                    Completion::Warning(res, stat)
-                } else {
-                    warn!("Encountered UEFI warning {:?}", stat);
-                    Completion::Warning(res, extra_stat)
-                }
-            }
-        }
+    fn warn_log(self) -> core::result::Result<T, Status> {
+        self.map(|completion| completion.value())
     }
-}
 
-impl<T> From<T> for Completion<T> {
-    fn from(res: T) -> Self {
-        Completion::Success(res)
+    fn warn_unwrap(self) -> T {
+        self.unwrap().unwrap()
     }
-}
 
-// This is a separate function to reduce the code size of the methods
-#[inline(never)]
-#[cold]
-fn unwrap_failed(msg: &str, warning: Status) -> ! {
-    panic!("{}: {:?}", msg, warning)
+    fn warn_expect(self, msg: &str) -> T {
+        self.expect(msg).expect(msg)
+    }
 }
-
-/// Return type of many UEFI functions.
-pub type Result<T> = result::Result<Completion<T>, Status>;

src/lib.rs

@@ -35,7 +35,7 @@ mod data_types;
 pub use self::data_types::{Event, Guid, Handle};
 
 mod error;
-pub use self::error::{Completion, Result, Status};
+pub use self::error::{Completion, Result, ResultExt, Status};
 
 pub mod table;
 

src/prelude.rs

@@ -2,7 +2,7 @@
 //!
 //! This includes the system table types, `Status` codes, etc.
 
-pub use crate::Status;
+pub use crate::{ResultExt, Status};
 
 // Import the basic table types.
 pub use crate::table::{boot::BootServices, runtime::RuntimeServices, SystemTable};