Merge pull request #1162 from godot-rust/qol/final-and-uninstantiable-classes

Final and non-instantiable classes

Author: Bromeon

godot-codegen/src/context.rs

@@ -271,8 +271,8 @@ impl<'a> Context<'a> {
         self.native_structures_types.contains(ty_name)
     }
 
-    pub fn is_singleton(&self, class_name: &str) -> bool {
-        self.singletons.contains(class_name)
+    pub fn is_singleton(&self, class_name: &TyName) -> bool {
+        self.singletons.contains(class_name.godot_ty.as_str())
     }
 
     pub fn inheritance_tree(&self) -> &InheritanceTree {

godot-codegen/src/generator/classes.rs

@@ -60,7 +60,7 @@ pub fn generate_class_files(
 struct GeneratedClass {
     code: TokenStream,
     notification_enum: NotificationEnum,
-    inherits_macro_ident: Ident,
+    inherits_macro_ident: Option<Ident>,
     /// Sidecars are the associated modules with related enum/flag types, such as `node_3d` for `Node3D` class.
     has_sidecar_module: bool,
 }
@@ -69,10 +69,17 @@ struct GeneratedClassModule {
     class_name: TyName,
     module_name: ModName,
     own_notification_enum_name: Option<Ident>,
-    inherits_macro_ident: Ident,
+    inherits_macro_ident: Option<Ident>,
     is_pub_sidecar: bool,
 }
 
+struct Construction {
+    constructor: TokenStream,
+    construct_doc: &'static str,
+    final_doc: Option<&'static str>,
+    godot_default_impl: TokenStream,
+}
+
 fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClass {
     let class_name = class.name();
 
@@ -90,8 +97,16 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         None => (quote! { crate::obj::NoBase }, None),
     };
 
-    let (constructor, construct_doc, godot_default_impl) = make_constructor_and_default(class, ctx);
-    let construct_doc = construct_doc.replace("Self", &class_name.rust_ty.to_string());
+    let Construction {
+        constructor,
+        construct_doc,
+        final_doc,
+        godot_default_impl,
+    } = make_constructor_and_default(class, ctx);
+
+    let mut extended_class_doc = construct_doc.replace("Self", &class_name.rust_ty.to_string());
+    extended_class_doc.push_str(final_doc.unwrap_or_default());
+
     let api_level = class.api_level;
     let init_level = api_level.to_init_level();
 
@@ -130,10 +145,10 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
 
     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);
     let deref_impl = make_deref_impl(class_name, &base_ty);
 
     let all_bases = ctx.inheritance_tree().collect_all_bases(class_name);
+    let (inherits_macro_ident, inherits_macro_code) = make_inherits_macro(class, &all_bases);
     let (notification_enum, notification_enum_name) =
         notifications::make_notification_enum(class_name, &all_bases, &cfg_attributes, ctx);
 
@@ -180,11 +195,6 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         }
     };
 
-    let inherits_macro_safety_doc = format!(
-        "The provided class must be a subclass of all the superclasses of [`{}`]",
-        class_name.rust_ty
-    );
-
     // mod re_export needed, because class should not appear inside the file module, and we can't re-export private struct as pub.
     let imports = util::make_imports();
     let tokens = quote! {
@@ -199,7 +209,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
             use super::*;
 
             #[doc = #class_doc]
-            #[doc = #construct_doc]
+            #[doc = #extended_class_doc]
             #cfg_attributes
             #[derive(Debug)]
             #[repr(C)]
@@ -247,20 +257,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
 
             #godot_default_impl
             #deref_impl
-
-            /// # Safety
-            ///
-            #[doc = #inherits_macro_safety_doc]
-            #[macro_export]
-            #[allow(non_snake_case)]
-            macro_rules! #inherits_macro {
-                ($Class:ident) => {
-                    unsafe impl ::godot::obj::Inherits<::godot::classes::#class_name> for $Class {}
-                    #(
-                        unsafe impl ::godot::obj::Inherits<::godot::classes::#all_bases> for $Class {}
-                    )*
-                }
-            }
+            #inherits_macro_code
         }
 
         #builders
@@ -275,11 +272,69 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
             name: notification_enum_name,
             declared_by_own_class: notification_enum.is_some(),
         },
-        inherits_macro_ident: inherits_macro,
+        inherits_macro_ident,
         has_sidecar_module,
     }
 }
 
+/// If the class can be inherited from (non-final), create a macro that can be accessed in subclasses to implement the `Inherits` trait.
+///
+/// Returns empty tokens if the class is final.
+fn make_inherits_macro(class: &Class, all_bases: &[TyName]) -> (Option<Ident>, TokenStream) {
+    let class_name = class.name();
+
+    // Create a macro that can be accessed in subclasses to implement the Inherits trait.
+    // Use this name because when typing a non-existent class, users will be met with the following error:
+    //    could not find `inherit_from_OS__ensure_class_exists` in `class_macros`
+    //
+    // Former macro name was `unsafe_inherits_transitive_*`.
+    let inherits_macro_ident =
+        format_ident!("inherit_from_{}__ensure_class_exists", class_name.rust_ty);
+
+    // For final classes, we can directly create a meaningful compile error.
+    if class.is_final {
+        let error_msg = format!(
+            "Class `{}` is final and cannot be inherited from.",
+            class_name.rust_ty
+        );
+
+        let code = quote! {
+            #[macro_export]
+            #[allow(non_snake_case)]
+            macro_rules! #inherits_macro_ident {
+                ($Class:ident) => {
+                    compile_error!(#error_msg);
+                }
+            }
+        };
+
+        return (None, code);
+    }
+
+    let inherits_macro_safety_doc = format!(
+        "The provided class must be a subclass of all the superclasses of [`{}`]",
+        class_name.rust_ty
+    );
+
+    let code = quote! {
+        /// # Safety
+        ///
+        #[doc = #inherits_macro_safety_doc]
+        #[macro_export]
+        #[allow(non_snake_case)]
+        macro_rules! #inherits_macro_ident {
+            ($Class:ident) => {
+                unsafe impl ::godot::obj::Inherits<::godot::classes::#class_name> for $Class {}
+                #(
+                    unsafe impl ::godot::obj::Inherits<::godot::classes::#all_bases> for $Class {}
+                )*
+            }
+        }
+    };
+
+    (Some(inherits_macro_ident), code)
+}
+
 fn make_class_module_file(classes_and_modules: Vec<GeneratedClassModule>) -> TokenStream {
     let mut class_decls = Vec::new();
     let mut notify_decls = Vec::new();
@@ -318,6 +373,11 @@ fn make_class_module_file(classes_and_modules: Vec<GeneratedClassModule>) -> Tok
             ..
         } = m;
 
+        // For final classes, do nothing.
+        let Some(inherits_macro_ident) = inherits_macro_ident else {
+            return TokenStream::new();
+        };
+
         // We cannot re-export the following, because macro is in the crate root
         // pub use #module_ident::re_export::#inherits_macro_ident;
         quote! {
@@ -341,17 +401,15 @@ fn make_class_module_file(classes_and_modules: Vec<GeneratedClassModule>) -> Tok
     }
 }
 
-fn make_constructor_and_default(
-    class: &Class,
-    ctx: &Context,
-) -> (TokenStream, &'static str, TokenStream) {
-    let godot_class_name = &class.name().godot_ty;
-    let godot_class_stringname = make_string_name(godot_class_name);
-    // Note: this could use class_name() but is not yet done due to upcoming lazy-load refactoring.
+fn make_constructor_and_default(class: &Class, ctx: &Context) -> Construction {
+    let class_name = class.name();
+
+    let godot_class_stringname = make_string_name(&class_name.godot_ty);
+    // Note: this could use class_name() but is not yet done due to potential future lazy-load refactoring.
     //let class_name_obj = quote! { <Self as crate::obj::GodotClass>::class_name() };
 
     let (constructor, construct_doc, has_godot_default_impl);
-    if ctx.is_singleton(godot_class_name) {
+    if ctx.is_singleton(class_name) {
         // Note: we cannot return &'static mut Self, as this would be very easy to mutably alias.
         // &'static Self would be possible, but we would lose the whole mutability information (even if that is best-effort and
         // not strict Rust mutability, it makes the API much more usable).
@@ -391,6 +449,15 @@ fn make_constructor_and_default(
         has_godot_default_impl = true;
     }
 
+    let final_doc = if class.is_final {
+        Some(
+            "\n\n# Final class\n\n\
+            This class is _final_, meaning you cannot inherit from it.",
+        )
+    } else {
+        None
+    };
+
     let godot_default_impl = if has_godot_default_impl {
         let class_name = &class.name().rust_ty;
         quote! {
@@ -404,7 +471,12 @@ fn make_constructor_and_default(
         TokenStream::new()
     };
 
-    (constructor, construct_doc, godot_default_impl)
+    Construction {
+        constructor,
+        construct_doc,
+        final_doc,
+        godot_default_impl,
+    }
 }
 
 fn make_deref_impl(class_name: &TyName, base_ty: &TokenStream) -> TokenStream {

godot-codegen/src/generator/notifications.rs

@@ -60,7 +60,7 @@ pub fn make_notify_methods(class_name: &TyName, ctx: &mut Context) -> TokenStrea
 
 pub fn make_notification_enum(
     class_name: &TyName,
-    all_bases: &Vec<TyName>,
+    all_bases: &[TyName],
     cfg_attributes: &TokenStream,
     ctx: &mut Context,
 ) -> (Option<TokenStream>, Ident) {

godot-codegen/src/models/domain.rs

@@ -161,6 +161,8 @@ pub struct Class {
     pub is_refcounted: bool,
     pub is_instantiable: bool,
     pub is_experimental: bool,
+    /// `true` if inheriting the class is disallowed.
+    pub is_final: bool,
     pub inherits: Option<String>,
     pub api_level: ClassCodegenLevel,
     pub constants: Vec<ClassConstant>,

godot-codegen/src/models/domain_mapping.rs

@@ -91,6 +91,9 @@ impl Class {
 
         // Already checked in is_class_deleted(), but code remains more maintainable if those are separate, and it's cheap to validate.
         let is_experimental = special_cases::is_class_experimental(&ty_name.godot_ty);
+        let is_instantiable =
+            special_cases::is_class_instantiable(&ty_name).unwrap_or(json.is_instantiable);
+        let is_final = ctx.is_singleton(&ty_name) || special_cases::is_class_final(&ty_name);
 
         let mod_name = ModName::from_godot(&ty_name.godot_ty);
 
@@ -129,8 +132,9 @@ impl Class {
                 mod_name,
             },
             is_refcounted: json.is_refcounted,
-            is_instantiable: json.is_instantiable,
+            is_instantiable,
             is_experimental,
+            is_final,
             inherits: json.inherits.clone(),
             api_level: get_api_level(json),
             constants,

godot-codegen/src/special_cases/special_cases.rs

@@ -206,6 +206,42 @@ pub fn is_class_experimental(godot_class_name: &str) -> bool {
     }
 }
 
+/// Whether a class can be instantiated (overrides Godot's defaults in some cases).
+///
+/// Returns `None` if the Godot default should be taken.
+pub fn is_class_instantiable(class_ty: &TyName) -> Option<bool> {
+    let class_name = class_ty.godot_ty.as_str();
+
+    // The default constructor is available but callers meet with the following Godot error:
+    // "ERROR: XY can't be created directly. Use create_tween() method."
+    // for the following classes XY:
+    //Tween, PropertyTweener, PropertyTweener, IntervalTweener, CallbackTweener, MethodTweener, SubtweenTweener,
+
+    if class_name == "Tween" || class_name.ends_with("Tweener") {
+        return Some(false);
+    }
+
+    None
+}
+
+/// Whether a class is final, i.e. cannot be inherited from.
+///
+/// Note that cases where the final status can be inferred from other properties (e.g. being a singleton) are already handled outside this
+/// function.
+#[rustfmt::skip]
+pub fn is_class_final(class_ty: &TyName) -> bool {
+    match class_ty.godot_ty.as_str(){
+        // https://github.com/godot-rust/gdext/issues/1129
+        | "AudioStreamGeneratorPlayback"
+        | "AudioStreamPlaybackInteractive"
+        | "AudioStreamPlaybackPlaylist"
+        | "AudioStreamPlaybackPolyphonic"
+        | "AudioStreamPlaybackSynchronized"
+
+        => true, _ => false
+    }
+}
+
 /// Whether a method is available in the method table as a named accessor.
 #[rustfmt::skip]
 pub fn is_named_accessor_in_table(class_or_builtin_ty: &TyName, godot_method_name: &str) -> bool {

godot-macros/src/class/derive_godot_class.rs

@@ -69,7 +69,10 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
     #[cfg(not(all(feature = "register-docs", since_api = "4.3")))]
     let docs = quote! {};
     let base_class = quote! { ::godot::classes::#base_ty };
-    let inherits_macro = format_ident!("unsafe_inherits_transitive_{}", base_ty);
+
+    // Use this name because when typing a non-existent class, users will be met with the following error:
+    //    could not find `inherit_from_OS__ensure_class_exists` in `class_macros`.
+    let inherits_macro_ident = format_ident!("inherit_from_{}__ensure_class_exists", base_ty);
 
     let prv = quote! { ::godot::private };
     let godot_exports_impl = make_property_impl(class_name, &fields);
@@ -186,7 +189,7 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
             )
         ));
 
-        #prv::class_macros::#inherits_macro!(#class_name);
+        #prv::class_macros::#inherits_macro_ident!(#class_name);
     })
 }