Add "log-once" macro variants

Author: benfrankel

README.md

@@ -5,26 +5,32 @@
 [![License](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?style=for-the-badge)](https://github.com/benfrankel/tiny_bail)
 
 Bailing is an error-handling pattern that takes the middle path between `unwrap` and `?`:
-- Compared to `unwrap`: Bail will `return`, `continue`, or `break` instead of panicking.
-- Compared to `?`: Bail will log or quietly discard the error instead of propagating it.
+- Compared to `unwrap`: Bailing will `return`, `continue`, or `break` instead of panicking.
+- Compared to `?`: Bailing will log or quietly discard the error instead of returning it.
 
 The middle path avoids unwanted panics without the ergonomic challenges of propagating errors with `?`.
 
-This crate provides the following macro variants:
+This crate provides the following macro variants to determine the preferred behavior on failure:
 - [`or_return!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_return.html)
 - [`or_return_quiet!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_return_quiet.html)
+- [`or_return_log_once!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_return_log_once.html)
 - [`or_continue!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_continue.html)
 - [`or_continue_quiet!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_continue_quiet.html)
+- [`or_continue_log_once!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_continue_log_once.html)
 - [`or_break!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_break.html)
 - [`or_break_quiet!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_break_quiet.html)
+- [`or_break_log_once!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.or_break_log_once.html)
 
 Along with their tiny aliases:
 [`r!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.r.html),
 [`rq!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.rq.html),
+[`ro!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.ro.html),
 [`c!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.c.html),
 [`cq!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.cq.html),
-[`b!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.b.html), and
-[`bq!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.bq.html).
+[`co!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.co.html),
+[`b!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.b.html),
+[`bq!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.bq.html), and
+[`bo!`](https://docs.rs/tiny_bail/latest/tiny_bail/macro.bo.html).
 
 The macros support `Result`, `Option`, and `bool` types out of the box. You can implement
 [`IntoResult`](https://docs.rs/tiny_bail/latest/tiny_bail/trait.IntoResult.html) to extend this to other types.

src/lib.rs

@@ -1,26 +1,32 @@
 //! Tiny bailing convenience macros.
 //!
 //! Bailing is an error-handling pattern that takes the middle path between `unwrap` and `?`:
-//! - Compared to `unwrap`: Bail will `return`, `continue`, or `break` instead of panicking.
-//! - Compared to `?`: Bail will log or quietly discard the error instead of propagating it.
+//! - Compared to `unwrap`: Bailing will `return`, `continue`, or `break` instead of panicking.
+//! - Compared to `?`: Bailing will log or discard the error instead of returning it.
 //!
 //! The middle path avoids unwanted panics without the ergonomic challenges of propagating errors with `?`.
 //!
-//! This crate provides the following macro variants:
+//! This crate provides the following macro variants to determine the preferred behavior on failure:
 //! - [`or_return!`]
 //! - [`or_return_quiet!`]
+//! - [`or_return_log_once!`]
 //! - [`or_continue!`]
 //! - [`or_continue_quiet!`]
+//! - [`or_continue_log_once!`]
 //! - [`or_break!`]
 //! - [`or_break_quiet!`]
+//! - [`or_break_log_once!`]
 //!
 //! Along with their tiny aliases:
 //! [`r!`](prelude::r),
 //! [`rq!`](prelude::rq),
+//! [`ro!`](prelude::ro),
 //! [`c!`](prelude::c),
 //! [`cq!`](prelude::cq),
-//! [`b!`](prelude::b), and
-//! [`bq!`](prelude::bq).
+//! [`co!`](prelude::co),
+//! [`b!`](prelude::b),
+//! [`bq!`](prelude::bq), and
+//! [`bo!`](prelude::bo).
 //!
 //! The macros support [`Result`], [`Option`], and [`bool`] types out of the box.
 //! Implement [`IntoResult`] to extend this to other types.
@@ -350,6 +356,67 @@ macro_rules! or_break_quiet {
     };
 }
 
+/// A helper macro to unwrap on success, or log the first failure and do something else.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! __unwrap_or_log_once {
+    ($expr:expr, $else:expr) => {
+        match $crate::IntoResult::into_result($expr) {
+            ::core::result::Result::Ok(x) => x,
+            ::core::result::Result::Err(__err) => {
+                static SHOULD_LOG: ::core::sync::atomic::AtomicBool =
+                    ::core::sync::atomic::AtomicBool::new(true);
+                if SHOULD_LOG.swap(false, ::core::sync::atomic::Ordering::Relaxed) {
+                    $crate::__log_bail!($expr, __err);
+                }
+                $else;
+            }
+        }
+    };
+}
+
+/// Unwrap on success, or log the first failure and return.
+///
+/// Returns [`Default::default()`] unless an initial argument is provided to return instead.
+#[macro_export]
+macro_rules! or_return_log_once {
+    ($return:expr, $expr:expr $(,)?) => {
+        $crate::__unwrap_or_log_once!($expr, return $return)
+    };
+
+    ($expr:expr $(,)?) => {
+        $crate::__unwrap_or_log_once!($expr, return ::core::default::Default::default())
+    };
+}
+
+/// Unwrap on success, or log the first failure and continue.
+///
+/// Accepts an optional 'label as the first argument.
+#[macro_export]
+macro_rules! or_continue_log_once {
+    ($label:tt, $expr:expr $(,)?) => {
+        $crate::__unwrap_or_log_once!($expr, continue $label)
+    };
+
+    ($expr:expr $(,)?) => {
+        $crate::__unwrap_or_log_once!($expr, continue)
+    };
+}
+
+/// Unwrap on success, or log the first failure and break.
+///
+/// Accepts an optional 'label as the first argument.
+#[macro_export]
+macro_rules! or_break_log_once {
+    ($label:tt, $expr:expr $(,)?) => {
+        $crate::__unwrap_or_log_once!($expr, break $label)
+    };
+
+    ($expr:expr $(,)?) => {
+        $crate::__unwrap_or_log_once!($expr, break)
+    };
+}
+
 #[cfg(test)]
 mod tests {
     use std::fmt::Debug;
@@ -436,6 +503,46 @@ mod tests {
         assert_eq!(bail(Err(()), -1), failure);
     }
 
+    #[test]
+    fn ro() {
+        fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E>, inner: T) -> i32 {
+            assert_eq!(or_return_log_once!(outer), inner);
+            2
+        }
+
+        // Success cases should fall through.
+        let success = 2;
+        assert_eq!(bail(true, true), success);
+        assert_eq!(bail(Some(-1), -1), success);
+        assert_eq!(bail(Ok::<_, ()>(-1), -1), success);
+
+        // Failure cases should return early with the default value.
+        let failure = 0;
+        assert_eq!(bail(false, true), failure);
+        assert_eq!(bail(None, -1), failure);
+        assert_eq!(bail(Err(()), -1), failure);
+    }
+
+    #[test]
+    fn ro_with_value() {
+        fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E>, inner: T) -> i32 {
+            assert_eq!(or_return_log_once!(1, outer), inner);
+            2
+        }
+
+        // Success cases should fall through.
+        let success = 2;
+        assert_eq!(bail(true, true), success);
+        assert_eq!(bail(Some(-1), -1), success);
+        assert_eq!(bail(Ok::<_, ()>(-1), -1), success);
+
+        // Failure cases should return early with the provided value.
+        let failure = 1;
+        assert_eq!(bail(false, true), failure);
+        assert_eq!(bail(None, -1), failure);
+        assert_eq!(bail(Err(()), -1), failure);
+    }
+
     #[test]
     fn c() {
         fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E> + Copy, inner: T) -> i32 {
@@ -552,6 +659,63 @@ mod tests {
         assert_eq!(bail(Err(()), -1), failure);
     }
 
+    #[test]
+    fn co() {
+        fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E> + Copy, inner: T) -> i32 {
+            let mut val = 0;
+            '_a: for _ in 0..2 {
+                val += 1;
+                for _ in 0..2 {
+                    val += 1;
+                    assert_eq!(or_continue_log_once!(outer), inner);
+                    val += 1;
+                }
+                val += 1;
+            }
+            val
+        }
+
+        // Success cases should fall through.
+        let success = 12;
+        assert_eq!(bail(true, true), success);
+        assert_eq!(bail(Some(-1), -1), success);
+        assert_eq!(bail(Ok::<_, ()>(-1), -1), success);
+
+        // Failure cases should continue early to the inner loop.
+        let failure = 8;
+        assert_eq!(bail(false, true), failure);
+        assert_eq!(bail(None, -1), failure);
+        assert_eq!(bail(Err(()), -1), failure);
+    }
+
+    #[test]
+    fn co_with_label() {
+        fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E> + Copy, inner: T) -> i32 {
+            let mut val = 0;
+            '_a: for _ in 0..2 {
+                val += 1;
+                for _ in 0..2 {
+                    val += 1;
+                    assert_eq!(or_continue_log_once!('_a, outer), inner);
+                    val += 1;
+                }
+                val += 1;
+            }
+            val
+        }
+
+        // Success cases should fall through.
+        let success = 12;
+        assert_eq!(bail(true, true), success);
+        assert_eq!(bail(Some(-1), -1), success);
+        assert_eq!(bail(Ok::<_, ()>(-1), -1), success);
+
+        // Failure cases should continue early to the outer loop.
+        let failure = 4;
+        assert_eq!(bail(false, true), failure);
+        assert_eq!(bail(None, -1), failure);
+        assert_eq!(bail(Err(()), -1), failure);
+    }
     #[test]
     fn b() {
         fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E> + Copy, inner: T) -> i32 {
@@ -667,4 +831,62 @@ mod tests {
         assert_eq!(bail(None, -1), failure);
         assert_eq!(bail(Err(()), -1), failure);
     }
+
+    #[test]
+    fn bo() {
+        fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E> + Copy, inner: T) -> i32 {
+            let mut val = 0;
+            '_a: for _ in 0..2 {
+                val += 1;
+                for _ in 0..2 {
+                    val += 1;
+                    assert_eq!(or_break_log_once!(outer), inner);
+                    val += 1;
+                }
+                val += 1;
+            }
+            val
+        }
+
+        // Success cases should fall through.
+        let success = 12;
+        assert_eq!(bail(true, true), success);
+        assert_eq!(bail(Some(-1), -1), success);
+        assert_eq!(bail(Ok::<_, ()>(-1), -1), success);
+
+        // Failure cases should break early from the inner loop.
+        let failure = 6;
+        assert_eq!(bail(false, true), failure);
+        assert_eq!(bail(None, -1), failure);
+        assert_eq!(bail(Err(()), -1), failure);
+    }
+
+    #[test]
+    fn bo_with_label() {
+        fn bail<T: Eq + Debug, E: Debug>(outer: impl IntoResult<T, E> + Copy, inner: T) -> i32 {
+            let mut val = 0;
+            '_a: for _ in 0..2 {
+                val += 1;
+                for _ in 0..2 {
+                    val += 1;
+                    assert_eq!(or_break_log_once!('_a, outer), inner);
+                    val += 1;
+                }
+                val += 1;
+            }
+            val
+        }
+
+        // Success cases should fall through.
+        let success = 12;
+        assert_eq!(bail(true, true), success);
+        assert_eq!(bail(Some(-1), -1), success);
+        assert_eq!(bail(Ok::<_, ()>(-1), -1), success);
+
+        // Failure cases should break early from the outer loop.
+        let failure = 2;
+        assert_eq!(bail(false, true), failure);
+        assert_eq!(bail(None, -1), failure);
+        assert_eq!(bail(Err(()), -1), failure);
+    }
 }