Code generation for engine-declared signals

Author: Bromeon

godot-codegen/src/generator/classes.rs

@@ -7,7 +7,9 @@
 use crate::context::{Context, NotificationEnum};
 use crate::generator::functions_common::{FnCode, FnDefinition, FnDefinitions};
 use crate::generator::method_tables::MethodTableKey;
-use crate::generator::{constants, docs, enums, functions_common, notifications, virtual_traits};
+use crate::generator::{
+    constants, docs, enums, functions_common, notifications, signals, virtual_traits,
+};
 use crate::models::domain::{
     ApiView, Class, ClassLike, ClassMethod, ExtensionApi, FnDirection, FnQualifier, Function,
     ModName, TyName,
@@ -121,6 +123,8 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         builders,
     } = make_class_methods(class, &class.methods, &cfg_attributes, ctx);
 
+    let signal_types = signals::make_class_signals(class, &class.signals, ctx);
+
     let enums = enums::make_enums(&class.enums, &cfg_attributes);
     let constants = constants::make_constants(&class.constants);
     let inherits_macro = format_ident!("unsafe_inherits_transitive_{}", class_name.rust_ty);
@@ -256,6 +260,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
 
         #builders
         #enums
+        #signal_types
     };
     // note: TypePtr -> ObjectPtr conversion OK?
 

godot-codegen/src/generator/mod.rs

@@ -25,6 +25,7 @@ pub mod lifecycle_builtins;
 pub mod method_tables;
 pub mod native_structures;
 pub mod notifications;
+pub mod signals;
 pub mod utility_functions;
 pub mod virtual_traits;
 

godot-codegen/src/generator/signals.rs

@@ -0,0 +1,215 @@
+/*
+ * 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/.
+ */
+
+// Code duplication: while there is some overlap with godot-macros/signal.rs for #[signal] handling, this file here is quite a bit simpler,
+// as it only deals with predefined signal definitions (no user-defined #[cfg], visibility, etc). On the other hand, there is documentation
+// for these signals, and integration is slightly different due to lack of WithBaseField trait. Nonetheless, some parts could potentially
+// be extracted into a future crate shared by godot-codegen and godot-macros.
+
+use crate::context::Context;
+use crate::conv;
+use crate::models::domain::{Class, ClassLike, ClassSignal, FnParam, RustTy, TyName};
+use crate::util::{ident, safe_ident};
+use proc_macro2::{Ident, TokenStream};
+use quote::{format_ident, quote};
+
+pub fn make_class_signals(
+    class: &Class,
+    signals: &[ClassSignal],
+    _ctx: &mut Context,
+) -> TokenStream {
+    if signals.is_empty() {
+        return TokenStream::new();
+    }
+
+    let all_params: Vec<SignalParams> = signals
+        .iter()
+        .map(|s| SignalParams::new(&s.parameters))
+        .collect();
+
+    let signal_collection_struct = make_signal_collection(class, signals, &all_params);
+
+    let signal_types = signals
+        .iter()
+        .zip(all_params.iter())
+        .map(|(signal, params)| make_signal_individual_struct(signal, params));
+
+    quote! {
+        #signal_collection_struct
+        #( #signal_types )*
+    }
+}
+
+// Used outside, to document class with links to this type.
+pub fn make_collection_name(class_name: &TyName) -> Ident {
+    format_ident!("SignalsIn{}", class_name.rust_ty)
+}
+
+fn make_individual_struct_name(signal_name: &str) -> Ident {
+    let signal_pascal_name = conv::to_pascal_case(signal_name);
+    format_ident!("Sig{}", signal_pascal_name)
+}
+
+fn make_signal_collection(
+    class: &Class,
+    signals: &[ClassSignal],
+    params: &[SignalParams],
+) -> TokenStream {
+    let class_name = class.name();
+    let collection_struct_name = make_collection_name(class_name);
+
+    let provider_methods = signals.iter().zip(params).map(|(sig, params)| {
+        let signal_name_str = &sig.name;
+        let signal_name = ident(&sig.name);
+        let individual_struct_name = make_individual_struct_name(&sig.name);
+        let provider_docs = format!("Signature: `({})`", params.formatted_types);
+
+        quote! {
+            // Important to return lifetime 'c here, not '_.
+            #[doc = #provider_docs]
+            pub fn #signal_name(&mut self) -> #individual_struct_name<'c> {
+                #individual_struct_name {
+                    typed: crate::registry::signal::TypedSignal::new(self.__gd.clone(), #signal_name_str)
+                }
+            }
+        }
+    });
+
+    let collection_docs = format!(
+        "A collection of signals for the [`{c}`][crate::classes::{c}] class.",
+        c = class_name.rust_ty
+    );
+
+    quote! {
+        #[doc = #collection_docs]
+        #[cfg(since_api = "4.2")]
+        pub struct #collection_struct_name<'c> {
+            __gd: &'c mut Gd<re_export::#class_name>,
+        }
+
+        #[cfg(since_api = "4.2")]
+        impl<'c> #collection_struct_name<'c> {
+            #( #provider_methods )*
+        }
+
+        #[cfg(since_api = "4.2")]
+        impl crate::obj::WithSignals for re_export::#class_name {
+            type SignalCollection<'c> = #collection_struct_name<'c>;
+            #[doc(hidden)]
+            type __SignalObject<'c> = Gd<re_export::#class_name>;
+
+            #[doc(hidden)]
+            fn __signals_from_external(external: &mut Gd<Self>) -> Self::SignalCollection<'_> {
+                Self::SignalCollection {
+                    __gd: external,
+                }
+            }
+        }
+    }
+}
+
+fn make_signal_individual_struct(signal: &ClassSignal, params: &SignalParams) -> TokenStream {
+    let individual_struct_name = make_individual_struct_name(&signal.name);
+
+    let SignalParams {
+        param_list,
+        type_list,
+        name_list,
+        ..
+    } = params;
+
+    let class_name = &signal.surrounding_class;
+    let class_ty = quote! { re_export::#class_name };
+    let param_tuple = quote! { ( #type_list ) };
+
+    quote! {
+        #[cfg(since_api = "4.2")]
+        pub struct #individual_struct_name<'c> {
+           pub typed: crate::registry::signal::TypedSignal<'c, #class_ty, #param_tuple>,
+        }
+
+        #[cfg(since_api = "4.2")]
+        impl #individual_struct_name<'_> {
+            pub fn emit(&mut self, #param_list) {
+                self.typed.emit_tuple( (#name_list) );
+            }
+        }
+
+        #[cfg(since_api = "4.2")]
+        impl<'c> std::ops::Deref for #individual_struct_name<'c> {
+            type Target = crate::registry::signal::TypedSignal<'c, #class_ty, #param_tuple>;
+
+            fn deref(&self) -> &Self::Target {
+                &self.typed
+            }
+        }
+
+        #[cfg(since_api = "4.2")]
+        impl std::ops::DerefMut for #individual_struct_name<'_> {
+            fn deref_mut(&mut self) -> &mut Self::Target {
+                &mut self.typed
+            }
+        }
+    }
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+struct SignalParams {
+    /// `name: Type, ...`
+    param_list: TokenStream,
+
+    /// `Type, ...` -- for example inside a tuple type.
+    type_list: TokenStream,
+
+    /// `name, ...` -- for example inside a tuple value.
+    name_list: TokenStream,
+
+    /// `"name: Type, ..."` in nice format.
+    formatted_types: String,
+}
+
+impl SignalParams {
+    fn new(params: &[FnParam]) -> Self {
+        use std::fmt::Write;
+
+        let mut param_list = TokenStream::new();
+        let mut type_list = TokenStream::new();
+        let mut name_list = TokenStream::new();
+        let mut formatted_types = String::new();
+        let mut first = true;
+
+        for param in params.iter() {
+            let param_name = safe_ident(&param.name.to_string());
+            let param_ty = &param.type_;
+
+            param_list.extend(quote! { #param_name: #param_ty, });
+            type_list.extend(quote! { #param_ty, });
+            name_list.extend(quote! { #param_name, });
+
+            let formatted_ty = match param_ty {
+                RustTy::EngineClass { inner_class, .. } => format!("Gd<{inner_class}>"),
+                other => other.to_string(),
+            };
+
+            if first {
+                first = false;
+            } else {
+                write!(formatted_types, ", ").unwrap();
+            }
+
+            write!(formatted_types, "{}: {}", param_name, formatted_ty).unwrap();
+        }
+
+        Self {
+            param_list,
+            type_list,
+            name_list,
+            formatted_types,
+        }
+    }
+}

godot-codegen/src/models/domain.rs

@@ -12,7 +12,7 @@
 
 use crate::context::Context;
 use crate::conv;
-use crate::models::json::{JsonMethodArg, JsonMethodReturn, JsonSignal};
+use crate::models::json::{JsonMethodArg, JsonMethodReturn};
 use crate::util::{ident, option_as_slice, safe_ident};
 
 use proc_macro2::{Ident, Literal, TokenStream};

godot-codegen/src/models/domain_mapping.rs

@@ -13,7 +13,12 @@ use crate::models::domain::{
     FunctionCommon, GodotApiVersion, ModName, NativeStructure, Operator, Singleton, TyName,
     UtilityFunction,
 };
-use crate::models::json::{JsonBuiltinClass, JsonBuiltinMethod, JsonBuiltinSizes, JsonClass, JsonClassConstant, JsonClassMethod, JsonConstructor, JsonEnum, JsonEnumConstant, JsonExtensionApi, JsonHeader, JsonMethodReturn, JsonNativeStructure, JsonOperator, JsonSignal, JsonSingleton, JsonUtilityFunction};
+use crate::models::json::{
+    JsonBuiltinClass, JsonBuiltinMethod, JsonBuiltinSizes, JsonClass, JsonClassConstant,
+    JsonClassMethod, JsonConstructor, JsonEnum, JsonEnumConstant, JsonExtensionApi, JsonHeader,
+    JsonMethodReturn, JsonNativeStructure, JsonOperator, JsonSignal, JsonSingleton,
+    JsonUtilityFunction,
+};
 use crate::util::{get_api_level, ident, option_as_slice};
 use crate::{conv, special_cases};
 use proc_macro2::Ident;
@@ -112,7 +117,7 @@ impl Class {
 
         let signals = option_as_slice(&json.signals)
             .iter()
-            .map(|s| {
+            .filter_map(|s| {
                 let surrounding_class = &ty_name;
                 ClassSignal::from_json(s, surrounding_class, ctx)
             })
@@ -524,12 +529,16 @@ impl ClassSignal {
         json_signal: &JsonSignal,
         surrounding_class: &TyName,
         ctx: &mut Context,
-    ) -> Self {
-        Self {
+    ) -> Option<Self> {
+        if special_cases::is_signal_deleted(surrounding_class, json_signal) {
+            return None;
+        }
+
+        Some(Self {
             name: json_signal.name.clone(),
             parameters: FnParam::new_range(&json_signal.arguments, ctx),
             surrounding_class: surrounding_class.clone(),
-        }
+        })
     }
 }
 

godot-codegen/src/special_cases/special_cases.rs

@@ -25,8 +25,9 @@
 
 use crate::conv::to_enum_type_uncached;
 use crate::models::domain::{Enum, RustTy, TyName};
-use crate::models::json::{JsonBuiltinMethod, JsonClassMethod, JsonUtilityFunction};
+use crate::models::json::{JsonBuiltinMethod, JsonClassMethod, JsonSignal, JsonUtilityFunction};
 use crate::special_cases::codegen_special_cases;
+use crate::util::option_as_slice;
 use crate::Context;
 use proc_macro2::Ident;
 // Deliberately private -- all checks must go through `special_cases`.
@@ -536,6 +537,14 @@ pub fn is_builtin_method_deleted(_class_name: &TyName, method: &JsonBuiltinMetho
     codegen_special_cases::is_builtin_method_excluded(method)
 }
 
+/// True if signal is absent from codegen (only when surrounding class is excluded).
+pub fn is_signal_deleted(_class_name: &TyName, signal: &JsonSignal) -> bool {
+    // If any argument type (a class) is excluded.
+    option_as_slice(&signal.arguments)
+        .iter()
+        .any(|arg| codegen_special_cases::is_class_excluded(&arg.type_))
+}
+
 /// True if builtin type is excluded (`NIL` or scalars)
 pub fn is_builtin_type_deleted(class_name: &TyName) -> bool {
     let name = class_name.godot_ty.as_str();

godot-core/src/obj/gd.rs

@@ -711,12 +711,17 @@ where
     /// Access user-defined signals of this object.
     ///
     /// For classes that have at least one `#[signal]` defined, returns a collection of signal names. Each returned signal has a specialized
-    /// API for connecting and emitting signals in a type-safe way. This method is the equivalent of [`WithSignals::signals()`], but when
-    /// called externally (not from `self`). If you are within the `impl` of a class, use `self.signals()` directly instead.
+    /// API for connecting and emitting signals in a type-safe way. This method is the equivalent of [`WithUserSignals::signals()`], but when
+    /// called externally (not from `self`). Furthermore, this is also available for engine classes, not just user-defined ones.
+    ///
+    /// When you are within the `impl` of a class, use `self.signals()` directly instead.
     ///
     /// If you haven't already, read the [book chapter about signals](https://godot-rust.github.io/book/register/signals.html) for a
     /// walkthrough.
-    pub fn signals(&self) -> T::SignalCollection<'_> {
+    ///
+    /// [`WithUserSignals::signals()`]: crate::obj::WithUserSignals::signals()
+    #[cfg(since_api = "4.2")]
+    pub fn signals(&mut self) -> T::SignalCollection<'_> {
         T::__signals_from_external(self)
     }
 }