Rename signal related symbols

Changes:
* connect_builder() -> builder()
* GodotDeref -> UniformObjectDeref

Author: Bromeon

godot-core/src/registry/signal/connect_builder.rs

@@ -22,7 +22,7 @@ use std::fmt::Debug;
 ///
 /// # Customization
 /// Customizing your signal connection must be done **before** providing the function being connected
-/// (can be done by using of the `connect_**` methods) (see section `Finalizing` bellow).
+/// (can be done by using of the `connect_*` methods) (see section `Finalizing` bellow).
 ///
 /// All these methods are optional, and they can be combined.
 // Use HTML link due to conditional compilation; renders badly if target symbol is unavailable.
@@ -40,6 +40,9 @@ use std::fmt::Debug;
 /// | `self`        | [`connect_self_mut`][Self::connect_self_mut]   | [`connect_self_gd`][Self::connect_self_gd]   |
 /// | other object  | [`connect_other_mut`][Self::connect_other_mut] | [`connect_other_gd`][Self::connect_other_gd] |
 ///
+/// Methods taking `&C` can (e.g. using interior mutability) can be indirectly connected through a `*_gd` overload + a `Gd::bind()` call.
+/// If this turns out to be a common use case, we could consider `connect_*_ref()` in the future.
+///
 /// <br>
 ///
 /// For **global functions, associated functions and closures**, you can use the following APIs:
@@ -143,8 +146,8 @@ macro_rules! impl_builder_connect {
             ///
             /// Example usages:
             /// ```ignore
-            /// sig.connect_builder().connect(Self::static_func);
-            /// sig.connect_builder().flags(ConnectFlags::DEFERRED).connect(global_func);
+            /// sig.builder().connect(Self::static_func);
+            /// sig.builder().flags(ConnectFlags::DEFERRED).connect(global_func);
             /// sig.connect(|arg| { /* closure */ });
             /// ```
             ///

godot-core/src/registry/signal/godot_deref.rs

@@ -8,21 +8,22 @@
 // Whole module only available in Godot 4.2+.
 
 mod connect_builder;
-mod godot_deref;
 mod signal_object;
 mod typed_signal;
+mod uniform_object_deref;
 
 use crate::builtin::{GString, Variant};
 use crate::meta;
 pub(crate) use connect_builder::*;
-use godot_deref::GodotDeref;
 pub(crate) use signal_object::*;
 pub(crate) use typed_signal::*;
+use uniform_object_deref::UniformObjectDeref;
 
 // Used in `godot` crate.
 pub mod re_export {
     pub use super::connect_builder::ConnectBuilder;
     pub use super::typed_signal::TypedSignal;
+    pub use super::uniform_object_deref::UniformObjectDeref;
 }
 
 // Used in `godot::private` module.

godot-core/src/registry/signal/mod.rs

@@ -5,7 +5,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use super::{make_callable_name, make_godot_fn, ConnectBuilder, GodotDeref, SignalObject};
+use super::{make_callable_name, make_godot_fn, ConnectBuilder, SignalObject, UniformObjectDeref};
 use crate::builtin::{Callable, Variant};
 use crate::classes::object::ConnectFlags;
 use crate::meta;
@@ -54,7 +54,7 @@ impl<C: WithBaseField> ToSignalObj<C> for C {
 /// - [`connect()`][Self::connect]: Connect a global/associated function or a closure.
 /// - [`connect_self()`][Self::connect_self]: Connect a method or closure that runs on the signal emitter.
 /// - [`connect_other()`][Self::connect_other]: Connect a method or closure that runs on a separate object.
-/// - [`connect_builder()`][Self::connect_builder] for more complex setups (such as choosing [`ConnectFlags`] or making thread-safe connections).
+/// - [`builder()`][Self::builder] for more complex setups (such as choosing [`ConnectFlags`] or making thread-safe connections).
 ///
 /// # Emitting a signal
 /// Code-generated signal types provide a method `emit(...)`, which adopts the names and types of the `#[signal]` parameter list.
@@ -119,8 +119,8 @@ impl<'c, C: WithSignals, Ps: meta::ParamTuple> TypedSignal<'c, C, Ps> {
     /// Fully customizable connection setup.
     ///
     /// The returned builder provides several methods to configure how to connect the signal. It needs to be finalized with a call
-    /// to any of the builder's `connect_**` methods.
-    pub fn connect_builder<'ts>(&'ts self) -> ConnectBuilder<'ts, 'c, C, Ps> {
+    /// to any of the builder's `connect_*` methods.
+    pub fn builder<'ts>(&'ts self) -> ConnectBuilder<'ts, 'c, C, Ps> {
         ConnectBuilder::new(self)
     }
 
@@ -189,7 +189,7 @@ macro_rules! impl_signal_connect {
             /// ```
             ///
             /// - To connect to a method on the object that owns this signal, use [`connect_self()`][Self::connect_self].
-            /// - If you need [`connect flags`](ConnectFlags) or cross-thread signals, use [`connect_builder()`][Self::connect_builder].
+            /// - If you need [`connect flags`](ConnectFlags) or cross-thread signals, use [`builder()`][Self::builder].
             pub fn connect<F, R>(&self, mut function: F)
             where
                 F: FnMut($($Ps),*) -> R + 'static,
@@ -204,15 +204,15 @@ macro_rules! impl_signal_connect {
             /// Connect a method (member function) with `&mut self` as the first parameter.
             ///
             /// - To connect to methods on other objects, use [`connect_other()`][Self::connect_other].
-            /// - If you need [`connect flags`](ConnectFlags) or cross-thread signals, use [`connect_builder()`][Self::connect_builder].
-            pub fn connect_self<F, R, Decl>(&self, mut function: F)
+            /// - If you need [`connect flags`](ConnectFlags) or cross-thread signals, use [`builder()`][Self::builder].
+            pub fn connect_self<F, R, Declarer>(&self, mut function: F)
             where
                 F: FnMut(&mut C, $($Ps),*) -> R + 'static,
-                C: GodotDeref<Decl>,
+                C: UniformObjectDeref<Declarer>,
             {
                 let mut gd = self.receiver_object();
                 let godot_fn = make_godot_fn(move |($($args,)*):($($Ps,)*)| {
-                    let mut target = C::get_mut(&mut gd);
+                    let mut target = C::object_as_mut(&mut gd);
                     let target_mut = target.deref_mut();
                     function(target_mut, $($args),*);
                 });
@@ -231,16 +231,16 @@ macro_rules! impl_signal_connect {
             /// ---
             ///
             /// - To connect to methods on the object that owns this signal, use [`connect_self()`][Self::connect_self].
-            /// - If you need [`connect flags`](ConnectFlags) or cross-thread signals, use [`connect_builder()`][Self::connect_builder].
-            pub fn connect_other<F, R, OtherC, Decl>(&self, object: &impl ToSignalObj<OtherC>, mut method: F)
+            /// - If you need [`connect flags`](ConnectFlags) or cross-thread signals, use [`builder()`][Self::builder].
+            pub fn connect_other<F, R, OtherC, Declarer>(&self, object: &impl ToSignalObj<OtherC>, mut method: F)
             where
                 F: FnMut(&mut OtherC, $($Ps),*) -> R + 'static,
-                OtherC: GodotDeref<Decl>,
+                OtherC: UniformObjectDeref<Declarer>,
             {
                 let mut gd = object.to_signal_obj();
 
                 let godot_fn = make_godot_fn(move |($($args,)*):($($Ps,)*)| {
-                    let mut target = OtherC::get_mut(&mut gd);
+                    let mut target = OtherC::object_as_mut(&mut gd);
                     let target_mut = target.deref_mut();
                     method(target_mut, $($args),*);
                 });

godot-core/src/registry/signal/typed_signal.rs

@@ -0,0 +1,101 @@
+/*
+ * 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::obj::bounds::{DeclEngine, DeclUser};
+use crate::obj::{Gd, GdMut, GdRef, GodotClass, WithBaseField};
+use std::ops::{Deref, DerefMut};
+
+/// Unifies dereferencing of user and engine classes, as `&T`/`&mut T` and `Gd<T>`.
+///
+/// This is mainly used by the `connect_*` functions of [`TypedSignal`](crate::registry::signal::TypedSignal).
+///
+/// # Motivation
+/// Although both user and engine classes are often wrapped in a `Gd<T>`, dereferencing them is done differently depending
+/// on whether they are made by the user or engine:
+/// - `Gd<EngineClass>` can be deref-ed directly into `&EngineClass` and `&mut EngineClass`.
+/// - `Gd<UserClass>` must first go through [`bind()`](Gd::bind)/[`bind_mut()`](Gd::bind_mut), which can finally
+///   be deref-ed into `&UserClass` and `&mut UserClass`, respectively.
+///
+/// Without this trait, there's no clear/generic way of writing functions that can accept both user and engine classes,
+/// but need to deref said classes in some way.
+///
+/// [`UniformObjectDeref`](Self) solves this by explicitly handling each category in a different way, but still resulting
+/// in a variable that can be deref-ed into `&T`/`&mut T`.
+///
+/// # Generic param `Declarer`
+/// Rustc [does not acknowledge associated type bounds when checking for overlapping impls](https://github.com/rust-lang/rust/issues/20400),
+/// this parameter is essentially used to create 2 different traits, one for each "category" (user or engine).
+///
+/// Despite being 2 different traits, a function can accept both by simply being generic over `Declarer`:
+/// ```no_run
+/// # use godot::register::UniformObjectDeref;
+/// # use godot::prelude::*;
+/// fn abstract_over_objects<Declarer, C>(obj: &Gd<C>)
+/// where
+///     C: UniformObjectDeref<Declarer>,
+/// {
+///     let ref_provider = UniformObjectDeref::object_as_ref(obj);
+///     let obj_ref: &C = & *ref_provider;
+///     // Regardless of `Declarer`, we can still deref, since the bounds on
+///     // `TargetRef`/`TargetMut` enforce that.
+/// }
+///
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct MyClass {
+///     _base: Base<RefCounted>
+/// }
+///
+/// fn main() {
+///     let engine_obj: Gd<RefCounted> = RefCounted::new_gd();
+///     let user_obj: Gd<MyClass> = MyClass::new_gd();
+///
+///     abstract_over_objects(&engine_obj);
+///     abstract_over_objects(&user_obj);
+/// }
+/// ```
+//
+// The crate `https://crates.io/crates/disjoint_impls` handles this in a more user-friendly way, we should
+// consider using it if disjoint impls are going to be frequently used.
+//
+// See also Declarer::DerefTarget in the library, which has a similar but different purpose: finding the nearest engine class
+// (`&Node` for `Node`, `&Node` for `MyClass`).
+#[allow(clippy::needless_lifetimes)] // False positive.
+pub trait UniformObjectDeref<Declarer>: GodotClass {
+    // Currently, only the mut parts are used within the library; but ref might be useful too.
+    type TargetRef<'a>: Deref<Target = Self>;
+    type TargetMut<'a>: DerefMut<Target = Self>;
+
+    fn object_as_ref<'a>(gd: &'a Gd<Self>) -> Self::TargetRef<'a>;
+    fn object_as_mut<'a>(gd: &'a mut Gd<Self>) -> Self::TargetMut<'a>;
+}
+
+#[allow(clippy::needless_lifetimes)] // False positive.
+impl<T: GodotClass<Declarer = DeclEngine>> UniformObjectDeref<DeclEngine> for T {
+    type TargetRef<'a> = Gd<T>;
+    type TargetMut<'a> = Gd<T>;
+
+    fn object_as_ref<'a>(gd: &'a Gd<Self>) -> Self::TargetRef<'a> {
+        gd.clone()
+    }
+    fn object_as_mut<'a>(gd: &'a mut Gd<Self>) -> Self::TargetMut<'a> {
+        gd.clone()
+    }
+}
+
+#[allow(clippy::needless_lifetimes)] // False positive.
+impl<T: WithBaseField> UniformObjectDeref<DeclUser> for T {
+    type TargetRef<'a> = GdRef<'a, T>;
+    type TargetMut<'a> = GdMut<'a, T>;
+
+    fn object_as_ref<'a>(gd: &'a Gd<Self>) -> Self::TargetRef<'a> {
+        gd.bind()
+    }
+    fn object_as_mut<'a>(gd: &'a mut Gd<Self>) -> Self::TargetMut<'a> {
+        gd.bind_mut()
+    }
+}