Merge pull request #1333 from godot-rust/qol/script-call-error

Add higher-level `CallErrorType` for script instance APIs

Author: Bromeon

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

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use crate::sys;
+
+/// Enum representing different errors during script instance calls.
+///
+/// Provides a type-safe way to handle call errors when implementing [`ScriptInstance::call()`](crate::obj::script::ScriptInstance::call).
+/// It maps to the underlying `GDExtensionCallErrorType` constants from Godot's C API.
+///
+/// Note that the `OK` variant is not included here, as it represents a successful call. This type is meant to be used in
+/// `Result<T, CallErrorType>`, where `Ok(T)` indicates success.
+///
+/// See [`SiMut::base_mut()`][crate::obj::script::SiMut::base_mut] for an example.
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+#[repr(C)]
+#[non_exhaustive]
+pub enum CallErrorType {
+    /// The method is invalid or was not found.
+    InvalidMethod = sys::GDEXTENSION_CALL_ERROR_INVALID_METHOD as isize,
+
+    /// One or more arguments cannot be converted to the expected parameter types.
+    InvalidArgument = sys::GDEXTENSION_CALL_ERROR_INVALID_ARGUMENT as isize,
+
+    /// Too many arguments were provided to the method.
+    TooManyArguments = sys::GDEXTENSION_CALL_ERROR_TOO_MANY_ARGUMENTS as isize,
+
+    /// Too few arguments were provided to the method.
+    TooFewArguments = sys::GDEXTENSION_CALL_ERROR_TOO_FEW_ARGUMENTS as isize,
+
+    /// The instance is null.
+    InstanceIsNull = sys::GDEXTENSION_CALL_ERROR_INSTANCE_IS_NULL as isize,
+
+    /// The method is not const, but was called on a const instance.
+    MethodNotConst = sys::GDEXTENSION_CALL_ERROR_METHOD_NOT_CONST as isize,
+}
+
+impl CallErrorType {
+    /// Converts the enum variant to its underlying `GDExtensionCallErrorType` value.
+    // Used to be result_to_sys(), but not really simplifying things at use site.
+    #[doc(hidden)]
+    pub const fn to_sys(self) -> sys::GDExtensionCallErrorType {
+        self as sys::GDExtensionCallErrorType
+    }
+
+    /// Creates a `CallErrorType` from a `GDExtensionCallErrorType` value.
+    ///
+    /// Returns `None` if the value doesn't correspond to a known error type.
+    ///
+    /// # Panics (Debug)
+    /// If the input doesn't match any known error type.
+    #[doc(hidden)]
+    pub fn result_from_sys(value: sys::GDExtensionCallErrorType) -> Result<(), Self> {
+        match value {
+            sys::GDEXTENSION_CALL_OK => Ok(()),
+            sys::GDEXTENSION_CALL_ERROR_INVALID_METHOD => Err(Self::InvalidMethod),
+            sys::GDEXTENSION_CALL_ERROR_INVALID_ARGUMENT => Err(Self::InvalidArgument),
+            sys::GDEXTENSION_CALL_ERROR_TOO_MANY_ARGUMENTS => Err(Self::TooManyArguments),
+            sys::GDEXTENSION_CALL_ERROR_TOO_FEW_ARGUMENTS => Err(Self::TooFewArguments),
+            sys::GDEXTENSION_CALL_ERROR_INSTANCE_IS_NULL => Err(Self::InstanceIsNull),
+            sys::GDEXTENSION_CALL_ERROR_METHOD_NOT_CONST => Err(Self::MethodNotConst),
+            _ => {
+                debug_assert!(false, "Unknown GDExtensionCallErrorType value: {value}");
+                Err(Self::InvalidMethod) // in Release builds, return known error.
+            }
+        }
+    }
+}

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

@@ -8,11 +8,13 @@
 //! Errors in the gdext library.
 
 mod call_error;
+mod call_error_type;
 mod convert_error;
 mod io_error;
 mod string_error;
 
 pub use call_error::*;
+pub use call_error_type::*;
 pub use convert_error::*;
 pub use io_error::*;
 pub use string_error::*;

godot-core/src/obj/script.rs

@@ -22,6 +22,7 @@ use godot_cell::panicking::{GdCell, MutGuard, RefGuard};
 
 use crate::builtin::{GString, StringName, Variant, VariantType};
 use crate::classes::{Object, Script, ScriptLanguage};
+use crate::meta::error::CallErrorType;
 use crate::meta::{MethodInfo, PropertyInfo};
 use crate::obj::{Base, Gd, GodotClass};
 use crate::sys;
@@ -113,12 +114,11 @@ pub trait ScriptInstance: Sized {
     /// mutable method calls like rust.
     ///
     /// It's important that the script does not cause a second call to this function while executing a method call. This would result in a panic.
-    // TODO: map the sys::GDExtensionCallErrorType to some public API type.
     fn call(
         this: SiMut<Self>,
         method: StringName,
         args: &[&Variant],
-    ) -> Result<Variant, sys::GDExtensionCallErrorType>;
+    ) -> Result<Variant, CallErrorType>;
 
     /// Identifies the script instance as a placeholder, routing property writes to a fallback if applicable.
     ///
@@ -400,7 +400,9 @@ impl<'a, T: ScriptInstance> SiMut<'a, T> {
     /// # use godot::classes::{ScriptLanguage, Script};
     /// # use godot::obj::script::{ScriptInstance, SiMut};
     /// # use godot::meta::{MethodInfo, PropertyInfo};
+    /// # use godot::meta::error::CallErrorType;
     /// # use godot::sys;
+    ///
     /// struct ExampleScriptInstance;
     ///
     /// impl ScriptInstance for ExampleScriptInstance {
@@ -410,7 +412,7 @@ impl<'a, T: ScriptInstance> SiMut<'a, T> {
     ///         this: SiMut<Self>,
     ///         method: StringName,
     ///         args: &[&Variant],
-    ///     ) -> Result<Variant, sys::GDExtensionCallErrorType>{
+    ///     ) -> Result<Variant, CallErrorType>{
     ///         let name = this.base().get_name();
     ///         godot_print!("name is {name}");
     ///         // However, we cannot call methods that require `&mut Base`, such as:
@@ -456,7 +458,9 @@ impl<'a, T: ScriptInstance> SiMut<'a, T> {
     /// # use godot::classes::{ScriptLanguage, Script};
     /// # use godot::obj::script::{ScriptInstance, SiMut};
     /// # use godot::meta::{MethodInfo, PropertyInfo};
+    /// # use godot::meta::error::CallErrorType;
     /// # use godot::sys;
+    ///
     /// struct ExampleScriptInstance;
     ///
     /// impl ScriptInstance for ExampleScriptInstance {
@@ -466,7 +470,7 @@ impl<'a, T: ScriptInstance> SiMut<'a, T> {
     ///         mut this: SiMut<Self>,
     ///         method: StringName,
     ///         args: &[&Variant],
-    ///     ) -> Result<Variant, sys::GDExtensionCallErrorType> {
+    ///     ) -> Result<Variant, CallErrorType> {
     ///         // Check whether method is available on this script
     ///         if method == StringName::from("script_method") {
     ///             godot_print!("script_method called!");
@@ -817,7 +821,8 @@ mod script_instance_info {
     ) {
         // SAFETY: `p_method` is a valid [`StringName`] pointer.
         let method = unsafe { StringName::new_from_string_sys(p_method) };
-        // SAFETY: `p_args` is a valid array of length `p_argument_count`
+
+        // SAFETY: `p_args` is a valid array of length `p_argument_count`.
         let args = unsafe {
             Variant::borrow_ref_slice(
                 p_args,
@@ -845,7 +850,7 @@ mod script_instance_info {
                 sys::GDEXTENSION_CALL_OK
             }
 
-            Ok(Err(err)) => err,
+            Ok(Err(err)) => err.to_sys(),
 
             Err(_) => sys::GDEXTENSION_CALL_ERROR_INVALID_METHOD,
         };

itest/rust/src/builtin_tests/script/script_instance_tests.rs

@@ -13,11 +13,11 @@ use godot::classes::{
     ScriptLanguageExtension,
 };
 use godot::global::{Error, MethodFlags};
+use godot::meta::error::CallErrorType;
 use godot::meta::{ClassId, FromGodot, MethodInfo, PropertyInfo, ToGodot};
 use godot::obj::script::{create_script_instance, ScriptInstance, SiMut};
 use godot::obj::{Base, Gd, NewAlloc, WithBaseField};
 use godot::register::{godot_api, GodotClass};
-use godot::sys;
 
 use crate::framework::itest;
 
@@ -166,7 +166,7 @@ impl ScriptInstance for TestScriptInstance {
         mut this: SiMut<Self>,
         method: StringName,
         args: &[&Variant],
-    ) -> Result<Variant, sys::GDExtensionCallErrorType> {
+    ) -> Result<Variant, CallErrorType> {
         match method.to_string().as_str() {
             "script_method_a" => {
                 let arg_a = args[0].to::<GString>();
@@ -190,7 +190,7 @@ impl ScriptInstance for TestScriptInstance {
 
             other => {
                 println!("CALL: {other} with args: {args:?}");
-                Err(sys::GDEXTENSION_CALL_ERROR_INVALID_METHOD)
+                Err(CallErrorType::InvalidMethod)
             }
         }
     }