EngineEnum: add values() + all_constants() functions

Author: Bromeon

godot-codegen/src/generator/enums.rs

@@ -13,6 +13,7 @@ use crate::models::domain::{Enum, Enumerator, EnumeratorValue, RustTy};
 use crate::special_cases;
 use proc_macro2::TokenStream;
 use quote::{quote, ToTokens};
+use std::collections::HashSet;
 
 pub fn make_enums(enums: &[Enum], cfg_attributes: &TokenStream) -> TokenStream {
     let definitions = enums.iter().map(make_enum_definition);
@@ -262,6 +263,7 @@ fn make_enum_engine_trait_impl(enum_: &Enum, enum_bitmask: Option<&RustTy>) -> T
         });
 
         let str_functions = make_enum_str_functions(enum_);
+        let values_and_constants_functions = make_enum_values_and_constants_functions(enum_);
 
         quote! {
             impl #engine_trait for #name {
@@ -277,6 +279,7 @@ fn make_enum_engine_trait_impl(enum_: &Enum, enum_bitmask: Option<&RustTy>) -> T
                 }
 
                 #str_functions
+                #values_and_constants_functions
             }
         }
     } else {
@@ -288,6 +291,7 @@ fn make_enum_engine_trait_impl(enum_: &Enum, enum_bitmask: Option<&RustTy>) -> T
 
         let unique_ords = enum_.unique_ords().expect("self is an enum");
         let str_functions = make_enum_str_functions(enum_);
+        let values_and_constants_functions = make_enum_values_and_constants_functions(enum_);
 
         // We can technically check against all possible mask values, remove each mask, and then verify it's a valid base-enum value.
         // However, this is not forward compatible: if a new mask is added in a future API version, it wouldn't be removed, and the
@@ -317,6 +321,49 @@ fn make_enum_engine_trait_impl(enum_: &Enum, enum_bitmask: Option<&RustTy>) -> T
                 }
 
                 #str_functions
+                #values_and_constants_functions
+            }
+        }
+    }
+}
+
+/// Creates both the `values()` and `all_constants()` implementations for the enum.
+fn make_enum_values_and_constants_functions(enum_: &Enum) -> TokenStream {
+    let name = &enum_.name;
+
+    let mut distinct_values = Vec::new();
+    let mut all_constants = Vec::new();
+    let mut seen_ordinals = HashSet::new();
+
+    for (index, enumerator) in enum_.enumerators.iter().enumerate() {
+        let constant = &enumerator.name;
+        let rust_name = enumerator.name.to_string();
+        let godot_name = enumerator.godot_name.to_string();
+        let ordinal = &enumerator.value;
+
+        // all_constants() includes every constant unconditionally.
+        all_constants.push(quote! {
+            crate::meta::inspect::EnumConstant::new(#rust_name, #godot_name, #ordinal, #name::#constant)
+        });
+
+        // values() contains value only if distinct (first time seen) and not MAX.
+        if enum_.max_index != Some(index) && seen_ordinals.insert(ordinal.clone()) {
+            distinct_values.push(quote! { #name::#constant });
+        }
+    }
+
+    quote! {
+        fn values() -> &'static [Self] {
+            &[
+                #( #distinct_values ),*
+            ]
+        }
+
+        fn all_constants() -> &'static [crate::meta::inspect::EnumConstant<#name>] {
+            const {
+                &[
+                    #( #all_constants ),*
+                ]
             }
         }
     }

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

@@ -129,7 +129,7 @@ pub struct Enumerator {
     pub value: EnumeratorValue,
 }
 
-#[derive(Clone)]
+#[derive(Clone, Hash, Eq, PartialEq)]
 pub enum EnumeratorValue {
     Enum(i32),
     Bitfield(u64),

godot-core/src/builtin/vectors/vector_axis.rs

@@ -54,6 +54,27 @@ macro_rules! impl_vector_axis_enum {
                     )+
                 }
             }
+
+            fn values() -> &'static [Self] {
+                // For vector axis enums, all values are distinct, so both are the same
+                &[
+                    $( $AxisEnum::$axis, )+
+                ]
+            }
+
+            fn all_constants() -> &'static [crate::meta::inspect::EnumConstant<$AxisEnum>] {
+                use crate::meta::inspect::EnumConstant;
+                const { &[
+                    $(
+                        EnumConstant::new(
+                            stringify!($axis),
+                            concat!("AXIS_", stringify!($axis)),
+                            $AxisEnum::$axis as i32,
+                            $AxisEnum::$axis
+                        ),
+                    )+
+                ] }
+            }
         }
 
         impl GodotConvert for $AxisEnum {

godot-core/src/meta/inspect.rs

@@ -0,0 +1,56 @@
+/*
+ * 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/.
+ */
+
+//! Introspection metadata for Godot engine types.
+
+/// Metadata for a single enum constant.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct EnumConstant<T: Copy + 'static> {
+    rust_name: &'static str,
+    godot_name: &'static str,
+    ord: i32,
+    value: T,
+}
+
+impl<T: Copy + 'static> EnumConstant<T> {
+    /// Creates a new enum constant metadata entry.
+    pub(crate) const fn new(
+        rust_name: &'static str,
+        godot_name: &'static str,
+        ord: i32,
+        value: T,
+    ) -> Self {
+        Self {
+            rust_name,
+            godot_name,
+            ord,
+            value,
+        }
+    }
+
+    /// Rust name of the enum variant, usually without Prefix (e.g. `"ESCAPE"` for `Key::ESCAPE`).
+    ///
+    /// This is returned by [`EngineEnum::as_str()`](crate::obj::EngineEnum::as_str()).
+    pub const fn rust_name(&self) -> &'static str {
+        self.rust_name
+    }
+
+    /// Godot constant name (e.g. `"KEY_ESCAPE"` for `Key::ESCAPE`).
+    pub const fn godot_name(&self) -> &'static str {
+        self.godot_name
+    }
+
+    /// Ordinal value of this enum variant.
+    pub const fn ord(&self) -> i32 {
+        self.ord
+    }
+
+    /// The enum value itself.
+    pub const fn value(&self) -> T {
+        self.value
+    }
+}

godot-core/src/meta/mod.rs

@@ -57,6 +57,7 @@ mod uniform_object_deref;
 pub(crate) mod sealed;
 
 pub mod error;
+pub mod inspect;
 
 pub use args::*;
 pub use class_name::ClassName;

godot-core/src/obj/traits.rs

@@ -8,6 +8,7 @@
 use crate::builder::ClassBuilder;
 use crate::builtin::GString;
 use crate::init::InitLevel;
+use crate::meta::inspect::EnumConstant;
 use crate::meta::ClassName;
 use crate::obj::{bounds, Base, BaseMut, BaseRef, Bounds, Gd};
 #[cfg(since_api = "4.2")]
@@ -187,15 +188,54 @@ pub trait EngineEnum: Copy {
             .unwrap_or_else(|| panic!("ordinal {ord} does not map to any enumerator"))
     }
 
-    // The name of the enumerator, as it appears in Rust.
-    //
-    // If the value does not match one of the known enumerators, the empty string is returned.
+    /// The name of the enumerator, as it appears in Rust.
+    ///
+    /// Note that **this may not match the Rust constant name!** In case of multiple constants with the same ordinal value, this method returns
+    /// the first one in the order of definition. For example, `LayoutDirection::LOCALE.as_str()` (ord 1) returns `"APPLICATION_LOCALE"`, because
+    /// that happens to be the first constant with ordinal `1`. See [`all_constants()`][Self::all_constants] for a more robust and general
+    /// approach to introspection of enum constants.
+    ///
+    /// If the value does not match one of the known enumerators, the empty string is returned.
     fn as_str(&self) -> &'static str;
 
-    // The equivalent name of the enumerator, as specified in Godot.
-    //
-    // If the value does not match one of the known enumerators, the empty string is returned.
+    /// The equivalent name of the enumerator, as specified in Godot.
+    ///
+    /// If the value does not match one of the known enumerators, the empty string is returned.
     fn godot_name(&self) -> &'static str;
+
+    /// Returns a slice of distinct enum values.
+    ///
+    /// This excludes MAX constants and deduplicates aliases, providing only meaningful enum values.
+    ///
+    /// This enables iteration over distinct enum variants:
+    /// ```no_run
+    /// use godot::classes::window;
+    /// use godot::obj::EngineEnum;
+    ///
+    /// for mode in window::Mode::values() {
+    ///     println!("* {}: {}", mode.as_str(), mode.ord());
+    /// }
+    /// ```
+    fn values() -> &'static [Self];
+
+    /// Returns metadata for all enum constants.
+    ///
+    /// This includes all constants as they appear in the enum definition, including duplicates and MAX constants.
+    ///
+    /// This enables complete introspection and debugging:
+    /// ```no_run
+    /// use godot::classes::window;
+    /// use godot::obj::EngineEnum;
+    ///
+    /// for constant in window::Mode::all_constants() {
+    ///     println!("* {}: {} (ord: {})",
+    ///         constant.rust_name(),
+    ///         constant.godot_name(),
+    ///         constant.ord()
+    ///     );
+    /// }
+    /// ```
+    fn all_constants() -> &'static [EnumConstant<Self>];
 }
 
 /// Auto-implemented for all engine-provided bitfields.

itest/rust/src/engine_tests/engine_enum_test.rs

@@ -7,7 +7,8 @@
 
 use crate::framework::itest;
 
-use godot::global::{Key, KeyModifierMask};
+use godot::classes::{mesh, window};
+use godot::global::{InlineAlignment, Key, KeyModifierMask, Orientation};
 use godot::obj::{EngineBitfield, EngineEnum};
 
 #[itest]
@@ -46,3 +47,135 @@ fn enum_with_masked_bitfield_from_ord() {
     // let back = Key::try_from_ord(31);
     // assert_eq!(back, None, "don't deserialize invalid bitmasked enum");
 }
+
+#[itest]
+fn enum_values_class() {
+    let expected_modes = [
+        window::Mode::WINDOWED,
+        window::Mode::MINIMIZED,
+        window::Mode::MAXIMIZED,
+        window::Mode::FULLSCREEN,
+        window::Mode::EXCLUSIVE_FULLSCREEN,
+    ];
+
+    assert_eq!(window::Mode::values(), &expected_modes);
+}
+
+#[itest]
+fn enum_values_global() {
+    let expected_orientations = [Orientation::VERTICAL, Orientation::HORIZONTAL];
+
+    assert_eq!(Orientation::values(), &expected_orientations);
+}
+
+#[itest]
+fn enum_values_duplicates() {
+    // InlineAlignment has many duplicate ordinals, but values() should return only distinct ones
+    // The order matches the declaration order in the JSON API, not ordinal order
+    let expected = [
+        (InlineAlignment::TOP_TO, 0, true),
+        (InlineAlignment::CENTER_TO, 1, true),
+        (InlineAlignment::BASELINE_TO, 3, true),
+        (InlineAlignment::BOTTOM_TO, 2, true),
+        (InlineAlignment::TO_TOP, 0, false), // duplicate of TOP_TO
+        (InlineAlignment::TO_CENTER, 4, true),
+        (InlineAlignment::TO_BASELINE, 8, true),
+        (InlineAlignment::TO_BOTTOM, 12, true),
+        (InlineAlignment::TOP, 0, false), // duplicate of TOP_TO
+        (InlineAlignment::CENTER, 5, true),
+        (InlineAlignment::BOTTOM, 14, true),
+        (InlineAlignment::IMAGE_MASK, 3, false), // duplicate of BASELINE_TO
+        (InlineAlignment::TEXT_MASK, 12, false), // duplicate of TO_BOTTOM
+    ];
+
+    let all_constants = InlineAlignment::all_constants();
+    let mut expected_distinct_values = vec![];
+    for ((value, ord, is_distinct), c) in expected.into_iter().zip(all_constants) {
+        if is_distinct {
+            assert_eq!(c.rust_name(), value.as_str()); // First distinct.
+            expected_distinct_values.push(value);
+        }
+
+        assert_eq!(c.value(), value);
+        assert_eq!(c.ord(), ord);
+    }
+
+    assert_eq!(InlineAlignment::values(), &expected_distinct_values);
+
+    // Some known duplicates.
+    assert_eq!(InlineAlignment::TOP_TO, InlineAlignment::TO_TOP); // ord 0
+    assert_eq!(InlineAlignment::TOP_TO, InlineAlignment::TOP); // ord 0
+    assert_eq!(InlineAlignment::BASELINE_TO, InlineAlignment::IMAGE_MASK); // ord 3
+    assert_eq!(InlineAlignment::TO_BOTTOM, InlineAlignment::TEXT_MASK); // ord 12
+}
+
+#[itest]
+fn enum_values_max_excluded() {
+    let expected_array_types = [
+        mesh::ArrayType::VERTEX,
+        mesh::ArrayType::NORMAL,
+        mesh::ArrayType::TANGENT,
+        mesh::ArrayType::COLOR,
+        mesh::ArrayType::TEX_UV,
+        mesh::ArrayType::TEX_UV2,
+        mesh::ArrayType::CUSTOM0,
+        mesh::ArrayType::CUSTOM1,
+        mesh::ArrayType::CUSTOM2,
+        mesh::ArrayType::CUSTOM3,
+        mesh::ArrayType::BONES,
+        mesh::ArrayType::WEIGHTS,
+        mesh::ArrayType::INDEX,
+    ];
+
+    let array_types = mesh::ArrayType::values();
+    assert_eq!(array_types, &expected_array_types);
+    assert!(
+        !array_types.contains(&mesh::ArrayType::MAX),
+        "ArrayType::MAX should be excluded from values()"
+    );
+
+    // However, it should still be present in all_constants().
+    let all_constants = mesh::ArrayType::all_constants();
+    assert!(
+        all_constants
+            .iter()
+            .any(|c| c.value() == mesh::ArrayType::MAX),
+        "ArrayType::MAX should be present in all_constants()"
+    );
+}
+
+#[itest]
+fn enum_all_constants() {
+    let constants = InlineAlignment::all_constants();
+    assert!(
+        constants.len() > InlineAlignment::values().len(),
+        "all_constants() should include duplicates"
+    );
+
+    // Check one known constant.
+    let first = constants[0];
+    assert_eq!(first.rust_name(), "TOP_TO");
+    assert_eq!(first.godot_name(), "INLINE_ALIGNMENT_TOP_TO");
+    assert_eq!(first.ord(), 0);
+    assert_eq!(first.value(), InlineAlignment::TOP_TO);
+
+    // Check specific constants at known indices, with equal ordinals.
+    let known_a = constants[2];
+    let known_b = constants[11];
+
+    assert_eq!(known_a.ord(), 3);
+    assert_eq!(known_a.rust_name(), "BASELINE_TO");
+    assert_eq!(known_a.godot_name(), "INLINE_ALIGNMENT_BASELINE_TO");
+    assert_eq!(known_a.value(), InlineAlignment::BASELINE_TO);
+
+    assert_eq!(known_b.ord(), 3);
+    assert_eq!(known_b.rust_name(), "IMAGE_MASK");
+    assert_eq!(known_b.godot_name(), "INLINE_ALIGNMENT_IMAGE_MASK");
+    assert_eq!(known_b.value(), InlineAlignment::IMAGE_MASK);
+
+    // "Front-end" values are equal, too.
+    assert_eq!(
+        InlineAlignment::IMAGE_MASK.ord(),
+        InlineAlignment::BASELINE_TO.ord()
+    );
+}