Add func_bail! macro

Author: Bromeon

godot-core/src/meta/error/error_to_godot.rs

@@ -24,7 +24,7 @@ use crate::meta::{GodotConvert, ToGodot};
 /// One option is to make the GDScript function call fail, meaning the GDScript function will be aborted.
 /// This happens when you use `String` error type. The declared type on GDScript side is `T`.
 ///
-/// For a more ergonomic catch-all approach, use [`FuncError`] / [`FuncResult`] which lets you use `?` with any `impl Error` type.
+/// For a more ergonomic catch-all approach, use [`FuncError`] which lets you use `?` with any `impl Error` type.
 ///
 /// ```no_run
 /// # use godot::prelude::*;
@@ -108,6 +108,8 @@ use crate::meta::{GodotConvert, ToGodot};
 /// | `Array` with 0/1 elems | `Array<T>`       | `[val]`            | `[]`               | `a.is_empty()`<br>`a.front()` -- typed! |
 /// | custom `RustResult`    | `Gd<RustResult>` | wrap in class      | wrap in class      | `r.is_ok()`<br>`r.unwrap()`             |
 ///
+/// [`FuncError`]: crate::meta::error::FuncError
+/// [`func_bail!`]: crate::meta::error::func_bail
 pub trait ErrorToGodot<T: ToGodot>: Sized {
     /// The type to which `Result<T, Self>` is mapped on Godot side.
     type Mapped: GodotConvert;

godot-core/src/meta/error/func_error.rs

@@ -10,7 +10,6 @@
 use std::error::Error;
 use std::fmt;
 
-use crate::builtin::CowStr;
 use crate::meta::ToGodot;
 use crate::meta::error::ErrorToGodot;
 
@@ -22,16 +21,16 @@ use crate::meta::error::ErrorToGodot;
 /// Its main advantage over other [`ErrorToGodot`] types is that it preserves type safety: GDScript's static analysis sees the return type `T`.
 /// This is the (more common) happy path, returned from Rust as `Ok(T)`.
 ///
-/// `FuncError` enables  automatic conversions from other errors via `?` operator. This means you can mix different error types within the same
-/// function body -- each one just propagates via `?` and its message is forwarded to Godot. `String` and `&str` also convert, for cases where
-/// you want to fail with a direct message.
+/// `FuncError` enables automatic conversions from other errors via `?` operator. This means you can mix different error types within the same
+/// function body -- each one propagates via `?` and its message is forwarded to Godot. `String` and `&str` also convert, for cases where you
+/// want to fail with a direct message.
 ///
-/// Use [`FuncResult<T>`] as a convenient alias for `Result<T, FuncError>`.
+/// Use [`FuncResult<T>`] as an alias for `Result<T, FuncError>`, and the [`func_bail!`] macro for early returns with an error message.
 ///
 /// # Example
 /// ```no_run
 /// # use godot::prelude::*;
-/// use godot::meta::error::FuncResult;
+/// use godot::meta::error::{FuncResult, func_bail};
 /// # #[derive(GodotClass)] #[class(init, base=Node)] struct PlayerData;
 ///
 /// #[godot_api]
@@ -44,9 +43,8 @@ use crate::meta::error::ErrorToGodot;
 ///         let text = std::fs::read_to_string(save_path.to_string())?;
 ///         let score = text.trim().parse::<i64>()?;
 ///
-///         // Strings are also supported via From trait.
 ///         if score < 0 {
-///             return Err(FuncError::from_message("Corrupted save file: high score is negative."));
+///             func_bail!("Corrupted save file {save_path}: high score is negative.");
 ///         }
 ///
 ///         Ok(score)
@@ -80,18 +78,6 @@ impl FuncError {
         }
     }
 
-    /// Create a `FuncError` from a plain message string.
-    ///
-    /// Accepts `&'static str` (no allocation) or `String` / `format!(...)` output. For non-static string slices, pass `.to_string()` or
-    /// use `format!()`. Useful when you want to fail a `#[func]` call with a plain message and have no underlying error type to propagate.
-    pub fn from_message(msg: impl Into<CowStr>) -> Self {
-        Self {
-            inner: Box::new(MessageError {
-                message: msg.into(),
-            }),
-        }
-    }
-
     /// Attempt to downcast the inner error to a concrete type.
     pub fn downcast_ref<E: Error + 'static>(&self) -> Option<&E> {
         self.inner.downcast_ref::<E>()
@@ -120,7 +106,7 @@ impl fmt::Debug for FuncError {
 /// |---|---|
 /// | Any `E: Error + Send + Sync + 'static` | Boxed directly; covers `std::io::Error`, `ParseIntError`, and any custom error type |
 /// | `Box<dyn Error + Send + Sync + 'static>` | Used as-is |
-/// | `String` | Wrapped in a message-only error (`StringError` in stdlib) |
+/// | `String` | Wrapped in a message-only error |
 /// | `&str` (any lifetime) | Copied to `String`, then wrapped — the lifetime is not propagated |
 impl<E: Into<Box<dyn Error + Send + Sync + 'static>>> From<E> for FuncError {
     fn from(err: E) -> Self {
@@ -152,24 +138,27 @@ impl<T: ToGodot<Via: Clone>> ErrorToGodot<T> for FuncError {
 pub type FuncResult<T> = Result<T, FuncError>;
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
-// Internal helper: wraps a plain message string as an error
+// Macro for immediately exiting function.
 
-#[derive(Debug)]
-struct MessageError {
-    message: CowStr,
-}
-
-impl fmt::Display for MessageError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.message)
-    }
+/// Return early from a `#[func]`, creating a [`FuncError`] from an error message.
+///
+/// Same principle as [`eyre::bail!`](https://docs.rs/eyre/latest/eyre/macro.bail.html),
+/// [`miette::bail!`](https://docs.rs/miette/latest/miette/macro.bail.html), and
+/// [`anyhow::bail!`](https://docs.rs/anyhow/latest/anyhow/macro.bail.html).
+///
+/// This macro expands to `return Err(FuncError::from(...))`.
+/// Accepts a string literal or a `format!`-style format string with arguments. See [`FuncError`] for usage example.
+#[macro_export]
+macro_rules! func_bail {
+    ($($arg:tt)*) => {
+        return ::std::result::Result::Err($crate::meta::error::FuncError::from(
+            ::std::format!($($arg)*)
+        ))
+    };
 }
 
-impl Error for MessageError {}
-
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-// Verify the From impls documented on the blanket From impl.
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -179,7 +168,7 @@ mod tests {
 
     #[test]
     fn from_concrete_error() {
-        // Any E: Error + Send + Sync + 'static -- here using ParseIntError.
+        // Accepts any E: Error + Send + Sync + 'static -- here ParseIntError.
         let err: Result<i32, _> = "x".parse();
         assert_func_error(err.unwrap_err().into());
     }
@@ -221,9 +210,21 @@ mod tests {
     }
 
     #[test]
-    fn from_message_constructor() {
-        let e = FuncError::from_message(format!("value was {}", 42));
-        assert_eq!(e.to_string(), "value was 42");
+    fn macro_literal_returns_early() {
+        fn run() -> FuncResult<i32> {
+            func_bail!("literal message");
+        }
+        let err = run().unwrap_err();
+        assert_eq!(err.to_string(), "literal message");
+    }
+
+    #[test]
+    fn macro_format_returns_early() {
+        fn run(x: i32) -> FuncResult<i32> {
+            func_bail!("value was {x}");
+        }
+        let err = run(42).unwrap_err();
+        assert_eq!(err.to_string(), "value was 42");
     }
 
     #[test]
@@ -235,7 +236,7 @@ mod tests {
 
     #[test]
     fn downcast_ref_wrong_type_returns_none() {
-        let e: FuncError = "not an io error".into();
+        let e: FuncError = "not an io::Error".into();
         assert!(e.downcast_ref::<std::io::Error>().is_none());
     }
 }

godot-core/src/meta/error/io_error.rs

@@ -12,7 +12,12 @@ use crate::classes::FileAccess;
 use crate::global::Error as GodotError;
 use crate::obj::Gd;
 
-/// Error that can occur while using `gdext` IO utilities.
+/// Error that can occur while using godot-rust I/O utilities.
+///
+/// Some APIs using this:
+/// - [`tools::try_load()`][crate::tools::try_load]
+/// - [`tools::try_save()`][crate::tools::try_save]
+/// - [`tools::GFile::try_from_unique()`][crate::tools::GFile::try_from_unique]
 #[derive(Debug)]
 pub struct IoError {
     data: ErrorData,

godot-core/src/meta/error/mod.rs

@@ -22,3 +22,5 @@ pub use error_to_godot::*;
 pub use func_error::*;
 pub use io_error::*;
 pub use string_error::*;
+
+pub use crate::func_bail;

godot/src/prelude.rs

@@ -14,7 +14,7 @@ pub use super::global::{
     godot_error, godot_print, godot_print_rich, godot_script_error, godot_warn,
 };
 pub use super::init::{ExtensionLibrary, InitLevel, InitStage, gdextension};
-pub use super::meta::error::{ConvertError, FuncError, FuncResult};
+pub use super::meta::error::ConvertError; // Possibly add later: FuncError, FuncResult, func_bail
 pub use super::meta::{FromGodot, GodotConvert, ToGodot};
 pub use super::obj::{
     AsDyn, Base, DynGd, DynGdMut, DynGdRef, Gd, GdMut, GdRef, GodotClass, Inherits, InstanceId,

itest/rust/src/register_tests/func_result_test.rs

@@ -7,7 +7,7 @@
 
 use godot::builtin::VariantType;
 use godot::global::Error;
-use godot::meta::error::{CallError, FuncError, FuncResult};
+use godot::meta::error::{CallError, FuncResult, func_bail};
 use godot::prelude::*;
 
 use crate::framework::itest;
@@ -61,7 +61,7 @@ impl FuncResulter {
 
     #[func]
     fn func_result_err_message(&self) -> FuncResult<i64> {
-        Err(FuncError::from_message("custom message"))
+        func_bail!("custom message");
     }
 
     #[func]
@@ -78,7 +78,7 @@ impl FuncResulter {
 
     #[func]
     fn func_result_err_str_literal(&self) -> FuncResult<i64> {
-        Err(FuncError::from_message("save file is corrupted"))
+        func_bail!("save file is corrupted");
     }
 
     #[func]