Merge pull request #1261 from ttencate/feature/synthetic_properties

Add PhantomVar<T> to support properties without a backing field

Author: Bromeon

godot-core/src/registry/property.rs renamed to godot-core/src/registry/property/mod.rs

@@ -16,6 +16,10 @@ use std::fmt::Display;
 use crate::meta::{ClassName, FromGodot, GodotConvert, GodotType, PropertyHintInfo, ToGodot};
 use crate::obj::{EngineEnum, GodotClass};
 
+mod phantom_var;
+
+pub use phantom_var::PhantomVar;
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Trait definitions
 

godot-core/src/registry/property/phantom_var.rs

@@ -0,0 +1,225 @@
+/*
+ * 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 std::{
+    cmp::Ordering,
+    fmt,
+    hash::{Hash, Hasher},
+    marker::PhantomData,
+};
+
+use crate::{
+    meta::{ClassName, GodotConvert, GodotType, PropertyHintInfo},
+    registry::property::{Export, Var},
+};
+
+/// A zero-sized type for creating a property without a backing field, accessible only through custom getter/setter functions.
+///
+/// This must be used in a struct deriving [`GodotClass`](../register/derive.GodotClass.html) and requires that the field has
+/// an explicit [`#[var]` attribute](../register/derive.GodotClass.html#register-properties--var) with a custom getter,
+/// and optionally a custom setter. Both getter and setter operate on the specified type `T`.
+///
+/// (Note that write-only properties, with a setter but not a getter, are not currently supported.
+/// Godot doesn't fully support them either, silently returning null instead of an error if the property is being read.)
+///
+/// # Example
+///
+/// Suppose you have a field `text` whose value you want to keep as a Rust `String` rather than a Godot `GString`,
+/// accepting the performance penalty for conversions whenever the property is accessed from Godot:
+///
+/// ```
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct Banner {
+///     #[var(get = get_text, set = set_text)]
+///     text: PhantomVar<GString>,
+///
+///     text_string: String,
+/// }
+///
+/// #[godot_api]
+/// impl Banner {
+///     #[func]
+///     fn get_text(&self) -> GString {
+///         GString::from(&self.text_string)
+///     }
+///
+///     #[func]
+///     fn set_text(&mut self, text: GString) {
+///         self.text_string = String::from(&text);
+///     }
+/// }
+/// ```
+///
+/// This field can now be accessed from GDScript as `banner.text`.
+// Bounds for T are somewhat un-idiomatically directly on the type, rather than impls.
+// This improves error messages in IDEs when using the type as a field.
+pub struct PhantomVar<T: GodotType + Var>(PhantomData<T>);
+
+impl<T: GodotType + Var> GodotConvert for PhantomVar<T> {
+    type Via = T;
+}
+
+// `PhantomVar` supports only part of `Var`, but it has to implement it, otherwise we cannot implement `Export` either.
+// The `GodotClass` derive macro should ensure that the `Var` implementation is not used.
+impl<T: GodotType + Var> Var for PhantomVar<T> {
+    fn get_property(&self) -> Self::Via {
+        unreachable!("code generated by GodotClass should call the custom getter")
+    }
+
+    fn set_property(&mut self, _value: Self::Via) {
+        unreachable!("code generated by GodotClass should call the custom setter");
+    }
+
+    fn var_hint() -> PropertyHintInfo {
+        <T as Var>::var_hint()
+    }
+}
+
+// Reuse values from `T`, if any.
+impl<T: GodotType + Var + Export> Export for PhantomVar<T> {
+    fn export_hint() -> PropertyHintInfo {
+        <T as Export>::export_hint()
+    }
+
+    fn as_node_class() -> Option<ClassName> {
+        <T as Export>::as_node_class()
+    }
+}
+
+impl<T: GodotType + Var> Default for PhantomVar<T> {
+    fn default() -> Self {
+        Self(Default::default())
+    }
+}
+
+// Like `PhantomData` from the Rust standard library, `PhantomVar` implements many common traits like `Eq` and `Hash`
+// to allow these traits to be derived on containing structs as well.
+
+impl<T: GodotType + Var> Clone for PhantomVar<T> {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<T: GodotType + Var> Copy for PhantomVar<T> {}
+
+impl<T: GodotType + Var> fmt::Debug for PhantomVar<T> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_tuple("PhantomVar").finish()
+    }
+}
+
+impl<T: GodotType + Var> PartialEq for PhantomVar<T> {
+    fn eq(&self, _other: &Self) -> bool {
+        true
+    }
+}
+
+impl<T: GodotType + Var> Eq for PhantomVar<T> {}
+
+impl<T: GodotType + Var> PartialOrd for PhantomVar<T> {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl<T: GodotType + Var> Ord for PhantomVar<T> {
+    fn cmp(&self, _other: &Self) -> Ordering {
+        Ordering::Equal
+    }
+}
+
+impl<T: GodotType + Var> Hash for PhantomVar<T> {
+    fn hash<H: Hasher>(&self, _state: &mut H) {}
+}
+
+/// This type exists only as a place to add `compile_fail` doctests for `PhantomVar`, which do not need to be in the public documentation.
+///
+/// Omitting the `#[var]` attribute is an error:
+///
+/// ```compile_fail
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct Oops {
+///     missing_var: PhantomVar<i64>,
+/// }
+/// ```
+///
+/// Declaring `#[var]` without a getter and/or setter is an error:
+///
+/// ```compile_fail
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct Oops {
+///     #[var]
+///     missing_get_set: PhantomVar<i64>,
+/// }
+/// ```
+///
+/// Declaring `#[var]` without a getter is an error:
+///
+/// ```compile_fail
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct Oops {
+///     #[var(set = setter)]
+///     missing_get: PhantomVar<i64>,
+/// }
+///
+/// #[godot_api]
+/// impl Oops {
+///     #[func]
+///     fn setter(&mut self, value: i64) {
+///     }
+/// }
+/// ```
+///
+/// Declaring `#[var]` with a default getter is an error:
+///
+/// ```compile_fail
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct Oops {
+///     #[var(get, set = setter)]
+///     default_get: PhantomVar<i64>,
+/// }
+///
+/// #[godot_api]
+/// impl Oops {
+///     #[func]
+///     fn setter(&mut self, value: i64) {
+///     }
+/// }
+/// ```
+///
+/// Declaring `#[var]` with a default setter is an error:
+///
+/// ```compile_fail
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init)]
+/// struct Oops {
+///     #[var(get = getter, set)]
+///     missing_set: PhantomVar<i64>,
+/// }
+///
+/// #[godot_api]
+/// impl Oops {
+///     #[func]
+///     fn getter(&self) -> i64 {
+///         0
+///     }
+/// }
+/// ```
+#[allow(dead_code)]
+struct PhantomVarDoctests;

godot-macros/src/class/data_models/field.rs

@@ -21,6 +21,7 @@ pub struct Field {
     pub subgroup: Option<FieldGroup>,
     pub is_onready: bool,
     pub is_oneditor: bool,
+    pub is_phantomvar: bool,
     #[cfg(feature = "register-docs")]
     pub attributes: Vec<venial::Attribute>,
     pub span: Span,
@@ -38,6 +39,7 @@ impl Field {
             subgroup: None,
             is_onready: false,
             is_oneditor: false,
+            is_phantomvar: false,
             #[cfg(feature = "register-docs")]
             attributes: field.attributes.clone(),
             span: field.span(),

godot-macros/src/class/data_models/field_var.rs

@@ -37,13 +37,8 @@ impl FieldVar {
     /// - `usage_flags =
     pub(crate) fn new_from_kv(parser: &mut KvParser) -> ParseResult<Self> {
         let span = parser.span();
-        let mut getter = GetterSetter::parse(parser, "get")?;
-        let mut setter = GetterSetter::parse(parser, "set")?;
-
-        if getter.is_omitted() && setter.is_omitted() {
-            getter = GetterSetter::Generated;
-            setter = GetterSetter::Generated;
-        }
+        let getter = GetterSetter::parse(parser, "get")?;
+        let setter = GetterSetter::parse(parser, "set")?;
 
         let hint = parser.handle_ident("hint")?;
 
@@ -77,6 +72,14 @@ impl FieldVar {
             span,
         })
     }
+
+    /// If both `get` and `set` are omitted, pretends that autogenerated getters and setters were requested.
+    pub(crate) fn default_to_generated_getter_setter(&mut self) {
+        if self.getter.is_omitted() && self.setter.is_omitted() {
+            self.getter = GetterSetter::Generated;
+            self.setter = GetterSetter::Generated;
+        }
+    }
 }
 
 impl Default for FieldVar {

godot-macros/src/class/data_models/property.rs

@@ -41,6 +41,7 @@ impl FieldHint {
 
 pub fn make_property_impl(class_name: &Ident, fields: &Fields) -> TokenStream {
     let mut getter_setter_impls = Vec::new();
+    let mut phantom_var_dummy_uses = Vec::new();
     let mut func_name_consts = Vec::new();
     let mut export_tokens = Vec::new();
 
@@ -163,6 +164,13 @@ pub fn make_property_impl(class_name: &Ident, fields: &Fields) -> TokenStream {
             class_name,
         );
 
+        if field.is_phantomvar {
+            let field_name = field.name.clone();
+            phantom_var_dummy_uses.push(quote! {
+                let _ = &self.#field_name;
+            });
+        }
+
         export_tokens.push(quote! {
             // This type may be reused in #hint, in case of generic functions.
             type FieldType = #field_type;
@@ -176,13 +184,29 @@ pub fn make_property_impl(class_name: &Ident, fields: &Fields) -> TokenStream {
         });
     }
 
+    let phantom_var_dummy_use_fn = if phantom_var_dummy_uses.is_empty() {
+        quote! {}
+    } else {
+        // `PhantomVar` fields are not normally accessed, resulting in undesired dead-code warnings.
+        // We are in a derive macro, so we cannot alter the original struct definition to add `#[allow(dead_code)]` to the field.
+        // Instead, we generate an unused, hidden function that mentions the field.
+        quote! {
+            #[expect(dead_code)]
+            #[doc(hidden)]
+            fn __phantom_var_dummy_uses(&self) {
+                #(#phantom_var_dummy_uses)*
+            }
+        }
+    };
+
     // For each generated #[func], add a const declaration.
     // This is the name of the container struct, which is declared by #[derive(GodotClass)].
     let class_functions_name = format_funcs_collection_struct(class_name);
 
     quote! {
         impl #class_name {
             #(#getter_setter_impls)*
+            #phantom_var_dummy_use_fn
         }
 
         impl #class_functions_name {