Merge pull request #728 from godot-rust/qol/exhaustive-enums

Exhaustive enums

Author: Bromeon

godot-codegen/src/generator/enums.rs

@@ -9,7 +9,7 @@
 //!
 //! See also models/domain/enums.rs for other enum-related methods.
 
-use crate::models::domain::{Enum, Enumerator};
+use crate::models::domain::{Enum, Enumerator, EnumeratorValue};
 use crate::{conv, util};
 use proc_macro2::TokenStream;
 use quote::{quote, ToTokens};
@@ -34,46 +34,67 @@ pub fn make_enum_definition_with(
     define_enum: bool,
     define_traits: bool,
 ) -> TokenStream {
+    assert!(
+        !(enum_.is_bitfield && enum_.is_exhaustive),
+        "bitfields cannot be marked exhaustive"
+    );
+
     // Things needed for the type definition
     let derives = enum_.derives();
     let enum_doc = make_enum_doc(enum_);
     let name = &enum_.name;
 
     // Values
-    let enumerators = enum_
-        .enumerators
-        .iter()
-        .map(|enumerator| make_enumerator_definition(enumerator, name.to_token_stream()));
+    let enumerators = enum_.enumerators.iter().map(|enumerator| {
+        make_enumerator_definition(enumerator, name.to_token_stream(), !enum_.is_exhaustive)
+    });
 
     // Various types
     let ord_type = enum_.ord_type();
     let engine_trait = enum_.engine_trait();
 
-    let definition = define_enum.then(|| {
-        let debug_impl = make_enum_debug_impl(enum_);
-
-        // Workaround because traits are defined in separate crate, but need access to field `ord`.
-        let vis = (!define_traits).then(|| {
+    let definition = if define_enum {
+        // Exhaustive enums are declared as Rust enums.
+        if enum_.is_exhaustive {
             quote! {
-                #[doc(hidden)] pub
+                #[repr(i32)]
+                #[derive(Debug, #( #derives ),* )]
+                #( #[doc = #enum_doc] )*
+                ///
+                /// This enum is exhaustive; you should not expect future Godot versions to add new enumerators.
+                #[allow(non_camel_case_types)]
+                pub enum #name {
+                    #( #enumerators )*
+                }
             }
-        });
+        }
+        //
+        // Non-exhaustive enums are declared as newtype structs with associated constants.
+        else {
+            // Workaround because traits are defined in separate crate, but need access to field `ord`.
+            let vis = (!define_traits).then(|| {
+                quote! { #[doc(hidden)] pub }
+            });
+
+            let debug_impl = make_enum_debug_impl(enum_);
+            quote! {
+                #[repr(transparent)]
+                #[derive( #( #derives ),* )]
+                #( #[doc = #enum_doc] )*
+                pub struct #name {
+                    #vis ord: #ord_type
+                }
 
-        quote! {
-            #[repr(transparent)]
-            #[derive( #( #derives ),* )]
-            #( #[doc = #enum_doc] )*
-            pub struct #name {
-                #vis ord: #ord_type
-            }
+                impl #name {
+                    #( #enumerators )*
+                }
 
-            impl #name {
-                #( #enumerators )*
+                #debug_impl
             }
-
-            #debug_impl
         }
-    });
+    } else {
+        TokenStream::new()
+    };
 
     let traits = define_traits.then(|| {
         // Trait implementations
@@ -185,6 +206,36 @@ fn make_enum_engine_trait_impl(enum_: &Enum) -> TokenStream {
                 }
             }
         }
+    } else if enum_.is_exhaustive {
+        let enumerators = enum_.enumerators.iter().map(|enumerator| {
+            let Enumerator {
+                name,
+                value: EnumeratorValue::Enum(ord),
+                ..
+            } = enumerator
+            else {
+                panic!("exhaustive enum contains bitfield enumerators")
+            };
+
+            quote! {
+                #ord => Some(Self::#name),
+            }
+        });
+
+        quote! {
+            impl #engine_trait for #name {
+                fn try_from_ord(ord: i32) -> Option<Self> {
+                    match ord {
+                        #( #enumerators )*
+                        _ => None,
+                    }
+                }
+
+                fn ord(self) -> i32 {
+                    self as i32
+                }
+            }
+        }
     } else {
         let unique_ords = enum_.unique_ords().expect("self is an enum");
 
@@ -238,13 +289,21 @@ fn make_enum_doc(enum_: &Enum) -> Vec<String> {
     docs
 }
 
-/// Creates a `const` definition for `enumerator` of the type `enum_type`.
+/// Creates a definition for `enumerator` of the type `enum_type`.
 ///
-/// That is, it'll be a definition like
+/// If `as_constant` is true, it will be a `const` definition like:
+/// ```ignore
+/// pub const NAME: enum_type = ord;
+/// ```
+/// Otherwise, it will be a regular enum variant like:
 /// ```ignore
-/// pub const NAME: enum_type = ..;
+/// NAME = ord,
 /// ```
-fn make_enumerator_definition(enumerator: &Enumerator, enum_type: TokenStream) -> TokenStream {
+fn make_enumerator_definition(
+    enumerator: &Enumerator,
+    enum_type: TokenStream,
+    as_constant: bool,
+) -> TokenStream {
     let Enumerator {
         name,
         godot_name,
@@ -262,11 +321,18 @@ fn make_enumerator_definition(enumerator: &Enumerator, enum_type: TokenStream) -
         TokenStream::new()
     };
 
-    quote! {
-        #docs
-        pub const #name: #enum_type = #enum_type {
-            ord: #value
-        };
+    if as_constant {
+        quote! {
+            #docs
+            pub const #name: #enum_type = #enum_type {
+                ord: #value
+            };
+        }
+    } else {
+        quote! {
+            #docs
+            #name = #value,
+        }
     }
 }
 

godot-codegen/src/models/domain/enums.rs

@@ -18,6 +18,7 @@ pub struct Enum {
     pub name: Ident,
     pub godot_name: String,
     pub is_bitfield: bool,
+    pub is_exhaustive: bool,
     pub enumerators: Vec<Enumerator>,
 }
 

godot-codegen/src/models/domain_mapping.rs

@@ -517,6 +517,7 @@ impl Enum {
     pub fn from_json(json_enum: &JsonEnum, surrounding_class: Option<&TyName>) -> Self {
         let godot_name = &json_enum.name;
         let is_bitfield = json_enum.is_bitfield;
+        let is_exhaustive = special_cases::is_enum_exhaustive(surrounding_class, godot_name);
 
         let rust_enum_name = conv::make_enum_name_str(godot_name);
         let rust_enumerator_names = {
@@ -550,6 +551,7 @@ impl Enum {
             name: ident(&rust_enum_name),
             godot_name: godot_name.clone(),
             is_bitfield,
+            is_exhaustive,
             enumerators,
         }
     }

godot-codegen/src/special_cases/special_cases.rs

@@ -354,3 +354,27 @@ pub fn is_class_level_server(class_name: &str) -> bool {
         => true, _ => false
     }
 }
+
+/// Certain enums that are extremely unlikely to get new identifiers in the future.
+/// 
+/// `class_name` = None for global enums.
+/// 
+/// Very conservative, only includes a few enums. Even `VariantType` was extended over time.
+/// Also does not work for any enums containing duplicate ordinals.
+#[rustfmt::skip]
+pub fn is_enum_exhaustive(class_name: Option<&TyName>, enum_name: &str) -> bool {
+    // Adding new enums here should generally not break existing code:
+    // * match _ patterns are still allowed, but cause a warning
+    // * Enum::CONSTANT access looks the same for proper enum and newtype+const
+    // Obviously, removing them will.
+
+    match (class_name, enum_name) {
+        | (None, "ClockDirection")
+        | (None, "Corner")
+        | (None, "EulerOrder")
+        | (None, "Side")
+        | (None, "Orientation")
+
+        => true, _ => false
+    }
+}

godot-core/src/builtin/basis.rs

@@ -12,6 +12,7 @@ use crate::builtin::math::{ApproxEq, FloatExt, GlamConv, GlamType};
 use crate::builtin::real_consts::FRAC_PI_2;
 use crate::builtin::{real, Quaternion, RMat3, RQuat, RVec2, RVec3, Vector3};
 
+use crate::engine::global::EulerOrder;
 use std::cmp::Ordering;
 use std::fmt::Display;
 use std::ops::{Mul, MulAssign};
@@ -322,6 +323,7 @@ impl Basis {
         ))
     }
 
+    #[allow(clippy::wrong_self_convention)]
     fn to_euler_inner(major: real, pair0: RVec2, pair1: RVec2, pair2: RVec2) -> RVec3 {
         match Self::is_between_neg1_1(major) {
             // It's -1
@@ -606,19 +608,6 @@ unsafe impl GodotFfi for Basis {
 
 impl_godot_as_self!(Basis);
 
-/// The ordering used to interpret a set of euler angles as extrinsic
-/// rotations.
-#[derive(Copy, Clone, Eq, PartialEq, Debug)]
-#[repr(C)]
-pub enum EulerOrder {
-    XYZ = 0,
-    XZY = 1,
-    YXZ = 2,
-    YZX = 3,
-    ZXY = 4,
-    ZYX = 5,
-}
-
 #[cfg(test)]
 mod test {
     use crate::builtin::real_consts::{FRAC_PI_2, PI};

godot-core/src/builtin/color.rs

@@ -368,31 +368,43 @@ impl ApproxEq for Color {
 #[derive(Copy, Clone, Eq, PartialEq, Debug)]
 pub enum ColorChannelOrder {
     /// RGBA channel order. Godot's default.
-    Rgba,
+    RGBA,
 
     /// ABGR channel order. Reverse of the default RGBA order.
-    Abgr,
+    ABGR,
 
     /// ARGB channel order. More compatible with DirectX.
-    Argb,
+    ARGB,
+}
+
+#[allow(non_upper_case_globals)]
+impl ColorChannelOrder {
+    #[deprecated(note = "Renamed to `ColorChannelOrder::RGBA`.")]
+    pub const Rgba: Self = Self::RGBA;
+
+    #[deprecated(note = "Renamed to `ColorChannelOrder::ABGR`.")]
+    pub const Abgr: Self = Self::ABGR;
+
+    #[deprecated(note = "Renamed to `ColorChannelOrder::ARGB`.")]
+    pub const Argb: Self = Self::ARGB;
 }
 
 impl ColorChannelOrder {
     fn pack<T>(self, rgba: [T; 4]) -> [T; 4] {
         let [r, g, b, a] = rgba;
         match self {
-            ColorChannelOrder::Rgba => [r, g, b, a],
-            ColorChannelOrder::Abgr => [a, b, g, r],
-            ColorChannelOrder::Argb => [a, r, g, b],
+            ColorChannelOrder::RGBA => [r, g, b, a],
+            ColorChannelOrder::ABGR => [a, b, g, r],
+            ColorChannelOrder::ARGB => [a, r, g, b],
         }
     }
 
     fn unpack<T>(self, xyzw: [T; 4]) -> [T; 4] {
         let [x, y, z, w] = xyzw;
         match self {
-            ColorChannelOrder::Rgba => [x, y, z, w],
-            ColorChannelOrder::Abgr => [w, z, y, x],
-            ColorChannelOrder::Argb => [y, z, w, x],
+            ColorChannelOrder::RGBA => [x, y, z, w],
+            ColorChannelOrder::ABGR => [w, z, y, x],
+            ColorChannelOrder::ARGB => [y, z, w, x],
         }
     }
 }

godot-core/src/builtin/mod.rs

@@ -151,14 +151,27 @@ pub(crate) fn u8_to_bool(u: u8) -> bool {
 /// The side of a [`Rect2`] or [`Rect2i`].
 ///
 /// _Godot equivalent: `@GlobalScope.Side`_
-#[doc(alias = "Side")]
-#[derive(Copy, Clone, Debug)]
-#[repr(C)]
-pub enum RectSide {
-    Left = 0,
-    Top = 1,
-    Right = 2,
-    Bottom = 3,
+#[deprecated(note = "Merged with `godot::global::Side`.")]
+pub type RectSide = crate::engine::global::Side;
+use crate::engine::global::Side;
+
+/// The ordering used to interpret a set of euler angles as extrinsic rotations.
+#[deprecated(note = "Merged with `godot::global::EulerOrder`.")]
+pub type EulerOrder = crate::engine::global::EulerOrder;
+
+#[allow(non_upper_case_globals)]
+impl Side {
+    #[deprecated(note = "Renamed to `Side::LEFT`.")]
+    pub const Left: Side = Side::LEFT;
+
+    #[deprecated(note = "Renamed to `Side::TOP`.")]
+    pub const Top: Side = Side::TOP;
+
+    #[deprecated(note = "Renamed to `Side::RIGHT`.")]
+    pub const Right: Side = Side::RIGHT;
+
+    #[deprecated(note = "Renamed to `Side::BOTTOM`.")]
+    pub const Bottom: Side = Side::BOTTOM;
 }
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------